HiveMQ Modules for Data Hub Specification (1.0)

Introduction

This specification provides a detailed description of the requirements, design, and functionality of HiveMQ Modules for Data Hub modules. In the Data Hub context, modules are used to deliver preliminarily pre-configured policies, schemas, and scripts to the broker in a single file. The module encapsulates everything needed to fulfill its intended purpose. In addition to Data Hub artifacts such as schemas, the module contains further details such as input parameters.

Once created, a module can be instantiated, meaning the Data Hub artifacts are executed within the broker based on the provided input parameters. To see a simple custom module example, check our hivemq-hello-world-datahub-module on GitHub .

Module File Format and Structure

A module is a compressed archive that contains multiple files. Each module file must adhere to the following requirements:

The module file must be compressed in ZIP format.

The minimum module archive file structure must include, but is not limited to, the following files:

Table 1. Minimum required module files
Name	Type	Required	Description
`index.json`	application/json		An index file that specifies metadata and the files relevant to the application of the module.
`variables.json`	application/json		A JSON schema that defines the input variables required to process the module.

Module Files and Parameters

Index JSON File

The index.json file specifies the exact purpose of the module and lists which files the module generates. This file also contains meta information such as the module name, description, and version.

Table 2. `index.json` file parameters
Field	Type	Description	Since
`name`	URL-safe characters	A concise identifier to help users correctly identify the module. For example, `hivemq-sparkplugB`.	v1.0
`version`	Semantic version	The version of the selected module according to the semantic versioning scheme `major.minor.patch`.	v1.0
`description`	String	Optional text that offers detailed information about the module and its functions.	v1.0
`resources`	Array of resource files	The resource files the module requires. For more information, see Resource Files	v1.0
`requiredSystemVersions`	String	The minimum required HiveMQ Platform version. For example, `hivemq-enterprise/4.30.0`.	v1.0
`maintainers`	Array of maintainers	The individuals who are responsible for the upkeep of the module. For more information, see Maintainer.	v1.0

Table 3. Resource file parameters
Field	Type	Description	Since
`type`	ContentType	The type of the file. File types include Data Hub schemas, scripts, and policies as well as documentation files such as PDF. For more information, see File Types.	v1.0
`path`	URL	The path to a file relevant to the module.	v1.0
`name`	String	A descriptive file name. This name can be particularly helpful to identify documentation files included in the module. For example, in a Sparkplug module that includes the Sparkplug specification as a PDF.	v1.0

Table 4. Available resource file types
MIME-Type	Description	Documentation
`application/vnd+hivemq.schema+json`	HiveMQ Data Hub schema.	Schemas
`application/vnd+hivemq.script+json`	HiveMQ Data Hub script.	Data Transformations
`application/vnd+hivemq.data-policy+json`	HiveMQ Data Hub Data Policy.	Data Policies
`application/vnd+hivemq.behavior-policy+json`	HiveMQ Data Hub Behavior Policy.	Behavior Policy

Table 5. Module maintainer parameters
Field	Type	Description	Since
`name`	String	The name of the maintainer.	v1.0
`email`	String	Optional setting to provide the email address of the maintainer.	v1.0
`url`	URL-safe characters	Optional setting to provide a URL for the maintainer. For example, a website.	v1.0

Variables JSON File

The file variables.json file defines the input parameters that can be used to configure the module. You can use the defined input parameters in resources such as your schema.json or data-policy.json using Apache Velocity syntax.

Example input parameters file

{
  "title": "SparkplugB module Variables",
  "type": "object",
  "required": [
    "topicPrefix",
    "fanout",
    "targetSchema"
  ],
  "properties": {
    "topicPrefix": {
      "type": "string",
      "title": "Topic Prefix",
      "description": "The MQTT topic prefix under the SparkplugB namespace lives"
    },
    "fanout": {
      "type": "boolean",
      "default": true,
      "title": "Fanout",
      "description": "The flag specifies whether the metrics should be splitted into separate metrics.."
    },
    "targetSchema": {
      "default": "JSON",
      "type": "string",
      "title": "Target value format",
      "description": "Sets the target value format",
      "enum": [
        "JSON",
        "PROTOBUF"
      ]
    }
  }
}

The example file defines three variables with default values:

topicPrefix: An MQTT topic variable (a predefined type according to the MQTT standard, $ref = /mqtt/topic).
fanout: A Boolean variable that determines whether the SparkplubB metrics are split into sub-topics.
targetSchema: A JSON or PROTOBUF variable that specifies how metrics are serialized.

HiveMQ Modules for Data Hub supports the following JSON Schema types:

String
Number
Boolean