General Rules of Thumb
There are three general rules of thumb to take into account when designing a QDM:
Use your common sense
Try to find the most elegant and economical way to represent your particular use case. While the Internet provides us with lots of rules, they may not always be ideal for your model.
Document your QDM to remove all ambiguities
The XML syntax Qeo uses for defining data models is excellently suited for expressing the structure of the data model, but it cannot capture the meaning of interactions in the data model. For example:
- What is the interpretation of each field in the data structure?
- Do some values have a special interpretation (e.g. setting an ID field to 0 may mean a request for the disposal of a certain instance)?
- What is the expected correlation between fields?
Therefore, you need to properly document your QDM. Use the <doc> element to do so. A QDM's documentation should allow any other developer to write components that flawlessly interface and inter-operate with it.
Be consistent
Use similar names for similar entities.
Publish Absolute Facts, not Relative Data
It is important to keep in mind that in a publish-subscribe system, one publishes information for asynchronous consumption. We strive to avoid request-response patterns as much as possible.
Therefore, it is best to design your data model in such a way that you publish absolute facts about your system, instead of relative data.
This concept is best illustrated with an example. Suppose you want to model the DHCP leases supplied by your DHCP server. In particular, for each lease you want to know how long it remains valid. In a request-response oriented system, it makes perfect sense to model this as a parameter called leaseTimeRemaining, which gives you the time in seconds this lease remains valid. For each request, you get a response that reflects accurately the lifetime this lease has left. In a publish-subscribe system, however, this model breaks down: the publisher has to update the state of each lease every second, because after a second the leaseTimeRemaining has changed, and the published information is out of date. Instead, it is better to model a DHCP lease as having an absolute endTime, which is a timestamp that tells us when the lease will expire. This absolute information remains valid for the entire lifetime of the lease, and must be published only once.
Don't Use Opaque Strings or Byte Arrays to Hide Your Data
Qeo offers you a rich type definition language that allows you to define a data type that accurately reflects all the information you want to provide in your data model. Make use of this facility. Do not define your data model as a single string in which you marshal all domain information yourself (e.g. in JSON format). There are several reasons for this:
- Qeo incorporates an efficient binary marshaling system. Rolling your own is just duplicate work.
- Thanks to Qeo's code generator, the rich data types you use on the wire are automatically translated to the equivalent data structures in your implementation language of choice.
- In the future, Qeo will include powerful querying and filtering features for data readers. On all kinds of readers, you'll be able to specify a filter expression that automatically drops all data you're not interested in. On StateReaders, you'll be able to retrieve instances based on an SQL-like query language (e.g. "get all instances where x > 5"). These features are currently under development, and they rely on the fact that Qeo knows the structure of your data type. If you hide away all semantically interesting information in some opaque member field, the query and filter mechanisms will be unavailable to you.
State Topics are Like Relational Database Tables
It can be very helpful to consider state topics as the equivalent of a table in a relational database. Instances on the topic are rows in the table, member fields translate to columns in the table. The key fields of the topic correspond to a table's primary key. Instances on a topic can refer to instances on other topics by including the key fields of this other topic, akin to a database table's foreign key.
From this point of view, we immediately have a whole set of well-known tools and techniques at our disposal to aid in datamodel design:
- Entity-Relationship diagrams
- Database normalization techniques (First, Second, Third, ... Normal Form)
However, like any analogy, this one breaks when you stretch it too far:
- "real" First Normal Form already forbids struct members that are themselves collections (sequences) or aggregate types (structures). On Qeo, it may make sense to use sequences and structures in some cases.
- Qeo does not guarantee referential integrity. When an instance disappears, instances on other topics that refer to it through their foreign keys are not automatically removed.