Created by lissensj on May 21, 2014

Use Well-known Names and Types for Common Concepts

Throughout all QDMs, we strive to have similar information and concepts represented in a similar way. This reduces the amount of effort needed to understand a "new" data model, and makes data models more self-documenting.

At Type Name Level
ConceptConvention
Type/Topic naming for Directed State Pattern (see State versus Event)
  • Give the "current state" topic a descriptive name (e.g. Actuator, BlacklistEntry, ...)
  • For the "desired state" topic, append "Request" to the name of the "current state" topic (e.g. ActuatorRequest, BlacklistEntryRequest, ...)

 

At Type Member Level
ConceptConvention
Unique ID as topic key
  • call the field "id"
  • use org::qeo::UUID as the field type
Reference to an instance on another topic
  • Duplicate the other topic's key fields as member fields in your topic
  • Special case: if the referenced topic's key is a UUID, call your field <referencedTopicName>Id
    e.g. we're referencing an instance on the Actuator topic, so we call our field "actuatorId" 
Date/time value
  • use an int64, which represents seconds since the Unix epoch (Jan 1, 1970) in UTC format (i.e. it does not take time zones or daylight saving time into account)
Duration/time interval
  • use an int32
  • default precision is seconds, if more precision is needed, indicate the relevant SI prefix (milli, micro, ...) in member name
IPv4 address
  • use a string
  • use dotted-quad notation, all decimal, no leading zeros
IPv6 address
  • use a string
  • use canonical form (see RFC 5952)
Ethernet MAC address
  • use a string
  • use canonical form: lowercase hex digits, separated by dashes (not colons) (e.g. 12-34-56-78-90-ab, not 12:34:56:78:90:AB)

Representing Non-Integral Quantities

Where possible, avoid the use of floating point numbers in data models. Qeo is targeted to run on embedded platforms, which typically have limited or no hardware support for floating point calculations. If feasible, choose a fixed-point representation with known precision, and use an integral type to represent your quantity.

For physical quantities, use the SI unit prefixes (milli, micro, mega, ...) to denote the precision of your field.

Representing Physical Quantities

Do not allow individual publishers of a data model to choose the unit in which a given physical quantity is represented. State the physical unit, and its precision, upfront in the QDM. Where possible, stick to SI units, and use an integral type to represent the quantity with a known precision (e.g. magnetism in nanoTesla, length in millimeters, ...).

Representing Enumerations

Often, your data model will contain information that's really best modeled as an enumeration (the state of a Finite State Machine, the wifi channel your access point is operating on, ...). 

Icon

At this point, Qeo does not yet support enumerations, but this feature will be added later. For now, it is good practice to model enumerations as an int32 field, and clearly explain the meaning of each value of the enumeration in documentation.

It is best not to use strings to represent enumeration values because:

  • it takes more bandwidth to send strings over the network
  • integer values are easier to map to the native enum type in your favorite programming language