To handle state and commands in Thing Interaction Framework, you need to define their data format beforehand. These data format definition is called the Schema. In Thing Interaction Framework, the schema is to be designed per service. It must be shared between the thing and mobile app.
The schema defines the data format of the state and the parameters of the commands (actions) to be sent to the thing.
The following figure illustrates an example of the schema.
You define the format of the State. The state can represent various aspects of the things, like the sensor data and the thing's current settings.
When the thing updates its state, it will upload the state to Thing Interaction Framework in the JSON format. In the schema, you define the field names and the field value types.
You define the format of the Command that will be sent from the mobile app to the thing.
The command is defined as an array of actions. Each action can have individual parameters, and you need to define their field names and data types. You also need to define the action names. In the schema, you need to define all actions.
For the action results, you just need to define their names. Their format is fixed (status and error message) and cannot be modified.
When you are done with defining the state and command, put the name and version to the schema, and you are all set.
If you are using the Android SDK, you will pass the schema information to the API (See Defining Schema to learn more details). If you are using the iOS or thing SDK, the schema information is used only as the implementation reference. As explained in the next section, however, you will use the schema name and version in the implementation.
Currently, the schema definition is not uploaded to Thing Interaction Framework. Thing Interaction Framework does not manage the schema definition, but it might do so in the future release (e.g., validating the data with the schema definition).
By leveraging the schema name and version, you can prevent problems that occur during the module upgrading.
The version mismatch can occur when you upgrade the program of the mobile app and thing. The thing side, in particular, needs to be prepared for this version mismatch; it must assume the reception of the commands that are based on the incomprehensible schema.
- If the mobile app is outdated, the command sent from this application will be based on the old schema version.
- If the thing is outdated, it will receive the command that is based on the unknown (new) schema.
The thing SDK will receive the schema name and version along with the command so that it can detect such situations.
The following figure illustrates the version mismatch problem. In the second situation, the thing will receive the command based on both the schema Ver. 1 and Ver. 2.
How to handle the version mismatch depends on the service specification. Please implement the appropriate logic for your service.
Please note that the states do not manage the schema version. If the thing is upgraded and sends the state fields that are not acknowledgeable by the mobile app, the mobile app will not be able to check these fields.
See Parsing Actions to learn how to check the schema name and version on the thing.