Model Evolution

Seldomly, an Aspect Model can be created completely in one step from ideation to conceptualization.

Authoring an Aspect Model is comparable to the creation of a software artifact. At first, a domain model draft or concept map is created to capture the understanding of the respective domain experts (cf. domain-driven design), which is then formalized into an actual Aspect Model. After multiple iterations, each of which improves the modeled concepts and the overall quality of the model, a first "complete" version is created. This first version might contain the minimal subset of relevant Properties complete with correct Characteristics and proper descriptions.

This "Version 1.0" of the model can then be used to implement the first version of the corresponding Aspect. Imagine that the service is running and delivers data that corresponds to the "Version 1.0" of the Aspect Model. Clients are developed as well, possibly by different parties, and happily consume the Aspect data. However, sooner or later there will be a need for change in the Aspect Model. For example, it could be missing relevant Properties, existing Properties could use wrong Characteristics, descriptions or names, or could be missing localizations. This can happen for many reasons:

It is to be expected that an Aspect Model is continually improved upon (to a certain point, when it is considered "finished"). The model maintainers can change the Aspect Model as they see fit and release a new version. But what happens with the running Aspects and clients? Do all of them have to be changed immediately every time?

The first measure towards a graceful evolution of Aspect Models in a living system (i.e., the models don’t live in a vacuum but are actually used by Aspects and Clients) is the decoupling of models and payload. In the section that describes the mapping of Aspect models to corresponding JSON payloads, you can see that the JSON payloads have no indication of the Aspect Model that describes them. In particular, they do not contain a reference to the URN of the corresponding Aspect Model. This is similar to how the structure of a JSON document can be validated against a JSON Schema.^[1]

Therefore there are changes that can be made in the Aspect Model so that the structure of the corresponding JSON payload does not change. We will call this type of changes safe changes. When a new version of an Aspect Model is released that contains only safe changes and a corresponding Aspect delivers only data that is valid in regards to the new version of the Aspect Model, the data is also still valid in regards to the previous version of the Aspect Model. The Aspect can therefore still be used by clients built using the previous version without having to be changed.

At the place used to look up the Aspect, the previous version of the Aspect Model and the updated version can and should both be associated simultaneously with the same Aspect endpoint. This allows clients that only understand the previous version of the Aspect Model to still consume data from the Aspect (although they do not benefit from the updates introduced in the new model version), while clients that are updated to use the new Aspect Model can benefit from the update.

At some point, older versions of the model can be removed from the Aspect. However, the exact conditions of when this can be done depend heavily on the concrete use case and are therefore out of scope of this document.

Every change to the Aspect Model that is backwards compatible in the sense that it permits all previously permitted JSON payloads and keeps semantics (see below) is a safe change.

The following table gives an overview of the safe and unchanges that mainly concern the structure of the data.

Deciding whether a change to a Characteristic is safe depends on the change itself. Basically, a change that adds restrictions on the value range is safe, while removing restrictions is unsafe, if and only if the effective value range was equivalent in the first place. For example, adding a Regular Expression Constraint that restricts values on a Text Characteristic is safe, because an Aspect that delivers data which is valid for both the previous version of the Aspect Model (without the Constraint) and for the new version (with the Constraint) will only ever deliver data that clients using the previous version of the Aspect Model can understand. Adding the constraint in the model just makes the previous implicit assumption explicit and visible. If the Constraint on the other hand signifies an actual change, i.e., values that were previously valid are no longer valid in the new version, this is an unsafe change.

If the value range is effectively the same and has the same meaning, for example by replacing a Regular Expression Expression on a Text Characteristic with an Enumeration that has the same values as those that would be parsed by the Regular Expression, or vice versa, this is a safe change as well. Changes such as this can be made when an Aspect Model is refactored to be better readable or understandable. Another example is changing a Characteristic with a string-like value space into a Structured Value: The payload does not change, but the meaning is specified in greater detail by describing all logical parts of the value.

Let’s consider a simple Aspect Model MachineOnlineStatus that describes a Property onlineStatus which represents the information about whether a machine is online, offline, starting up or undefined (if the current status can not be retrieved).