Packet Schemas

Packet Schemas are structured schemas containing typed fields, for datapoints and messages. Packet Schemas exist to ensure that the data and messages sent between your devices and Fostrom are exactly of the shape and types that you expect.

Before you can send any datapoint or message to Fostrom, you need to create a packet schema for it.

We use the terms Packet Schema and Schema interchangably.

Creating a Packet Schema

To create a new schema, click on the New Schema button in the Schemas tab.

You need to pick a name unique to your fleet, for the packet schema. And this time, the name does really matter. Devices will send the name of the packet schema when sending datapoints or messages. Hence, schema names cannot be changed once selected.

When creating a schema, you'll need to pick what is it for: datapoint or message. If you select Datapoint, there are no additional options.

If you select Message, you can set a Direction Constraint for the schema. This means that either the messages with this packet schema can only be sent from devices (Inbound), can only be sent from Fostrom and received by the device (Outbound), or the same packet schema can be used in both directions (helpful for broadcasting a message to other devices).

You should enter a description of what you aim to do with the packet schema, as it will be helpful for you and other members of your organization in the future.

Schema List

The list of schemas shows the name and description, along with a badge to indicate whether its a datapoint or message schema. If you set a direction constraint, another badge will also be shown with that detail.

Adding Fields to a Schema

Once you open a schema, you can add fields to it. Think of fields as the key-value pairs you want to send from your devices. Pick a name for the field. If you are tending to pick a shorter name to avoid consuming unnecessary bandwidth, you can, however, we are working on Device SDKs which will partially pre-process the packet on your device and avoid sending field names altogether. We're also going to add the ability to set a description, unit, and pretty-name of fields soon.

You can nest fields using a dot separator, but a parent field with another type should not already exist. For example: room: string cannot exist if you want to add room.temperature. This is because the object you'll send from your device will need to have a shape similar to {room: {temperature: <value>}}.

Currently, all fields are optional. We are in the process of significantly advancing schema evolution and are going to add the ability to make optional fields required in the future.

You need to select a type for the field. We currently support many different types:

  • signed and unsigned integers from 8-bits to 64-bits,
  • fixed-precision decimals
  • 64-bit floats
  • booleans
  • strings

We're going to introduce more types and composite types such as lists and sets soon.

Once you create a field, its type cannot be changed. This is to ensure the flow of data remains consistent throughout your fleet. However, you can "soft-delete" a field. It remains in the schema to ensure backwards compability, but you can reuse the name if you wish to.

A note of Schema Evolution and Backwards Compability

Schema Evolution is a core tenant of Fostrom, and we're going to introduce many more capabilities related to evolving your schemas rapidly.

The way we expect to maintain backwards compatibility and allow schema evolution is by having something we call a wire sequence on each field. It is the badge you see in your fields list besides the Optional badge. #0 indicates its the first field in the schema. Wire sequeneces are immutable and never reused. So even if you delete a field, a new field with the same name will get the next available wire sequenence.

We also avoid sending field names by sending the wire sequence of the field instead. Even though we support sending the wire sequence instead of the field name, we suggest you avoid sending the wire sequence manually. Our Device SDKs will automatically get new schema updates pushed to them so they can switch over to using new wire sequences automatically for a field of the same name.