Data Validation

Premium

Version 3.1

The data validation plugin allows to discard received messages based on their payload structure before they are published by the Mosquitto broker. To decide whether a message is rejected, its payload is validated against a JSON schema.

Features:

• Topic based message payload validation (Topic Mappings)
• Use JSON schema to define the format of a valid payload (Schemas)
• Support for topic wildcards
• Multiple topics can be validated by one or several schemas

Plugin activation

Ensure that the broker has a suitable license for using the Data Validation plugin. If that is the case the plugin can be activated by adding the following to the mosquitto.conf file:

plugin /usr/lib/cedalo_data_validation.so

caution

Please place this plugin before all other plugins in the mosquitto.conf.

Platform UI

The Cedalo Platform allows you to modify the configuration of the Data Validation plugin. Navigate to the broker, where you want to manage the plugin. Then select "Data Validation" from the navigation. If the entry is not available, your license or setup does not allow to use the Data Validation plugin. Either update your license or modify your configuration to enable it.

After selecting the "Data Validation" navigation entry, the following screen will appear (JSON contents might differ):

Here you can modify the configuration for the plugin. The configuration uses a json format, which is explained below. It has to match the json schema also provided below as well. Simply edit your configuration and save it once you are done editing. The config is not saved automatically.

If the provided configuration contains invalid JSON, a hint is displayed below the editor. In case the structure of the new configuration does not comply with the JSON schema an error message will pop up.

Configuration

The configuration consist of two parts:

• topicMappings: define which messages should be validated (Topic Mappings)
• schemas: a list of schemas to validate message payload (Schemas)

Topic Mappings

Topic mappings define which broker messages should be validated by assigning a schema to one or more topics. It is possible to validate a message with multiple schemas. In that case the message payload must fulfill all schemas.

note

• wildcards such as + (single-level) or # (multi-level) are supported too
• messages for which no matching topic mapping exists are not validated and therefore never discarded
• messages which have a mapped topic but no JSON payload are discarded by default

Following is an example of topic mappings that validate topic topicA against schema s1 and topicB against schemas s1 and s2:

{
    "topicMappings": [
        {
            "name": "mapping1",
            "schema": "s1",
            "topics": ["topicA", "topicB"]
        },
        {
            "name": "mapping2",
            "schema": "s2",
            "topics": ["topicB"]
        }
    ]
}

Schemas

A JSON schema defines the format that a message payload must fulfill. Each schema has a unique name property which is used to reference it within the topicMappings. The complete JSON schema definition is simply specified under schema.

Following example defines a schema s1 which requires a name property and another schema s2 which requires an age field

{
    "schemas": [
        {
            "name": "s1",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    }
                },
                "required": ["name"]
            }
        },
        {
            "name": "s2",
            "schema": {
                "type": "object",
                "properties": {
                    "age": {
                        "type": "number"
                    }
                },
                "required": ["age"]
            }
        }
    ]
}

JSON Schema

Following schema is used by the Data Validation plugin to validate any new configuration JSON:

{
  "title": "Data Validation Plugin Configuration",
  "description": "",
  "type": "object",
  "properties": {
    "topicMappings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Unique identifier of this topic mapping."
          },
          "schema": {
            "type": "string",
            "description": "Name of JSON schema to use for validating the message payload."
          },
          "topics": {
            "type": "array",
            "description": "List of topics whose payload should be validated against specified schema.",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "name",
          "schema",
          "topics"
        ]
      }
    },
    "schemas": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Unique identifier. Used to reference this schema within topic mapping."
          },
          "schema": {
            "type": "object",
            "description": "A JSON schema definition to validate the message payload."
          }
        },
        "required": [
          "name",
          "schema"
        ]
      }
    }
  },
  "required": [
    "topicMappings",
    "schemas"
  ]
};