HiveMQ Data Hub Quick Start Guide

In the HiveMQ Control Center main navigation, expand the Data Hub menu and select Schemas.
The Schemas overview for your HiveMQ deployment opens:

On the Schemas overview, select Add New Schema. A Schema Detail page opens:

When you create a schema, you need to specify a unique schema ID, the type of schema you want to create, and a description of the schema:

Enter an identifier for your schema in the Schema ID field. The schema ID is used to reference the schema in a policy and must be unique in the HiveMQ broker.
Each schema ID must begin with a letter and contain 1 to 1024 lowercase letters, uppercase letters, numbers, periods (.), hyphens (-), or underscores (_). In this guide, we use the schema ID gps_coordinates.

Select JSON in the Schema type field.
Possible values are JSON or PROTOBUF.
In this guide, we create a JSON Schema.

Copy and paste the following example schema definition into the Schema Definition field. The schema definition describes the JSON Schema and is used to validate and deserialize MQTT message payloads.

{
  "$id": "https://example.com/geographical-location.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Longitude and Latitude Values",
  "description": "A geographical coordinate.",
  "required": [
    "latitude",
    "longitude"
  ],
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum": 180
    }
  }
}

To save the gps_coordinates JSON Schema, select Save Schema.

In the HiveMQ Control Center main navigation, expand the Data Hub menu and select Data Policies.
The Data Policies overview for your HiveMQ deployment opens:

On the Data Policies overview, select Add New Policy. A Data Policy Detail page opens:

When you create a data policy, the first step is to define a unique policy ID, specify a matching topic filter that determines which MQTT messages the policy validates, and add the validation method you want the policy to use:

Enter an identifier for your policy in the Policy ID field. The Schema ID is used to reference the schema in a policy and must be unique in the HiveMQ broker.
Each schema ID must begin with a letter and contain 1 to 1024 lowercase letters, uppercase letters, numbers, periods (.), hyphens (-), or underscores (_). In this guide, we use the schema ID policy-coordinates.

Specify an MQTT topic filter in the Matching Topic Filter field to determine which MQTT message payloads the policy validates. The filter can be any valid MQTT topic filter, including wildcards. Each topic filter can only be used in one policy per HiveMQ cluster.
In this guide, we use the Matching Topic Filter coordinates/+.

To select how you want the data policy to validate MQTT topic payloads, select Add Schema Validator on the Validation tab of the Data Policy Detail. If no validator is specified, no validation takes place and every message payload is evaluated as a success. One policy can contain multiple validators.

The result of your schema-based validation can be success or failure.
Based on the validation outcome, you can define optional onFailure and onSuccess actions that take place when a validation finishes.

On the Action On Failure tab of the Data Policy Detail, select Add Task to define one or more tasks to take place if the outcome of a validation in this policy is failure. Data Hub executes the tasks of an action pipeline in your defined order.

From the Function menu, select an operation that occurs when a validation fails.
In this guide, we use System - Log Message to provide additional information.

On the Action On Success tab of the Data Policy Detail, select Add Task to define one or more tasks to take place if the outcome of a validation in this policy is success. Data Hub executes the tasks of an action pipeline in your defined order.

From the Function menu, select an operation that occurs when a validation succeeds.
In this guide, we use System - Log Message to provide additional information.

To complete your Data Policy, switch to the Summary tab of the Data Policy Detail and review the content of your policy draft:

To save your data policy, select Save Policy.

To edit or delete a Data Policy, return to the Policy Detail of the policy. To edit the policy, select the edit icon.
To delete the policy, select Delete.

To test your Data Hub setup, follow the procedure in the Test section to send messages that generate success and failure outcomes.