Message Concepts

Messages and Envelopes

An Avro Message contained in an Avro Message Envelope is refered to as an Enveloped Avro Message.

An Avro Message Envelope carries information about the Avro Message including the Topic and the Schema Fingerprint.

The Topic identifies which instance, of what logical entity, published (wrote) what attribute.

The Schema Fingerprint identifies the exact Avro Schema that was used to publish (write) the Avro Message.

Given the Schema Fingerprint the Avro Schema can be retrieved from an Avro Schema Registry. This publisher (writer) Avro Schema is needed to be able to deserialise the Avro Message contained in the Avro Message Envelope.

Avro Types & Versioning

The term Avro Type is used in this documentation to refer to a particular usage of named Avro types (in the Avro specification sense) where semantic versioning is incorporated into the naming of Avro types by appending a major version to the base name of the Avro type. For example version 1 of Foo is named Foo_v1.

We refer to an Avro Type Foo when we don't wish to or need to identify the version.

We refer to a particular exact version of Foo by using a major.minor version number.

The initial revison of Foo_, which has name _Foo_v1 is Foo version 1.0.

If Foo_v1 is revised in a compatible way it is now referred to as Foo version 1.1 etc.

A breaking change changes the major version number so the name becomes, in this example, Foo_v2 and we refer to this version of Foo as Foo version 2.0.

Messages in State Store

Topics can be considered to be keys for access to a State Store that holds the latest value published to that Topic. The value in the state store is an Enveloped Avro Message.

A given Topic in the State Store always refers to an Enveloped Avro Message containing an Avro Message of the same Avro Type (but an unspecified version of that Avro Type_). The actual version of the _Avro Type for a given Topic will change when/if the publisher is updated to use a newer version of the Avro Type.

Multiple Topics can (and generally will) refer to Enveloped Avro Messages containing Avro Messages of the same Avro Type.

As an example of multiple Topics referring to messages of the same Avro Type consider some entity of type E that publishes an attribute represented using some Avro Type A. Each instance of E is identified by an id. When an instance of E publishes the value of this attribute it uses a Topic of the general form E.<id>.A where <id> is distinct for each instance of E.

This pattern of identifying the entity publishing the attribute by entity type and entity identifier is applied recursively. For example if E has child entities of type C each identified (within the scope of E.<id>_) by _cid then the Topic E.<id>.C.<cid>.B refers to an Enveloped Avro Message of Avro Type B that was published by an instance of C that is a child of E.<id>.