When you call Thing Specification Language (TSL)-specific operations, the request parameters or response parameters contain the ThingModelJson parameter. The data format of this parameter indicates the storage structure of a TSL in IoT Platform. However, the data format of this parameter is different from the original data structure of the TSL. This topic describes the data format of the ThingModelJson parameter.

Data format

{
  “productKey":"",
  "_ppk":{
    "version":"",
    "description":""
  }
  "properties":[],//property List
  "services":[],//service List
  "events":[],//event List
}
Parameter Type Description
productKey String The key of the product to which the TSL belongs.
_ppk String The information of the TSL version. The TSL data includes the version and description parameters.
version String The version of the TSL. This parameter is available only for TSLs that have been published.
description String The description of the TSL version. This parameter is available only for TSLs that have been published.
properties List The property list in the TSL. For more information about the parameters included in the data format of a property, see Property data format.
services List The service list in the TSL. For more information about the parameters included in the data format of a service, see Service data format.
events List The event list in the TSL. For more information about the parameters included in the data format of an event, see Event data format.

Property data format

The following table lists the parameters that are included in the data format of a property.

Parameter Type Required Description
productKey String Yes The key of the product to which the TSL belongs.
identifier String Yes The identifier of the property. The identifier must be 50 characters in length and can contain uppercase and lowercase letters, digits, and underscores (_).
Note The identifier cannot be any of the following words: set, get, post, property, event, time, and value.
dataType String Yes The data type of the property value.

Valid values: ARRAY, STRUCT, INT, FLOAT, DOUBLE, TEXT, DATE, ENUM, and BOOL.

You can specify different parameters based on data types. For more information about how to specify parameters based on data types, see the corresponding sections in this topic.

name String Yes The name of the property. The name can contain Chinese characters, English letters, digits, hyphens (-), underscores (_), and periods (.). It must start with a Chinese character, English letter, or digit. The name must be up to 30 characters in length. A Chinese character is counted as one encoding character.
rwFlag String Yes The type of operation that IoT Platform can perform on the property.
  • READ_WRITE: read and write
  • READ_ONLY: read-only
  • WRITE_ONLY: write-only
dataSpecs Object No If you set the dataType parameter to any of the following values: INT, FLOAT, DOUBLE, TEXT, DATE, and ARRAY, the data format is included in the dataSpecs parameter.
Note The data format excludes the parameters that are used to define properties, services, and events.
dataSpecsList List No If you set the dataType parameter to any of the following values: ENUM, BOOL, and STRUCT, the data format is included in the dataSpecsList parameter.
Note The data format excludes the parameters that are used to define properties, services, and events.
required Boolean Yes Specifies whether the property is required for the standard category.
  • true: yes
  • false: no
custom Boolean Yes Specifies whether the property is a custom feature.
  • true: yes
  • false: no

Service data format

The following table lists the parameters that are included in the data format of a service.

Parameter Type Required Description
productKey String Yes The key of the product to which the TSL belongs.
identifier String Yes The identifier of the service. The identifier must be 50 characters in length and can contain uppercase and lowercase letters, digits, and underscores (_).
Note The identifier cannot be any of the following words: set, get, post, property, event, time, and value.
serviceName String Yes The name of the service. The name can contain Chinese characters, English letters, digits, hyphens (-), underscores (_), and periods (.). It must start with a Chinese character, English letter, or digit. The name must be up to 30 characters in length. A Chinese character is counted as one encoding character.
inputParams List No The input parameters of the service. For more information about the data format of an input parameter, see Data formats of input and output parameters.
outputParams List No The input parameters of the service. For more information about the data format of an output parameter, see Data formats of input and output parameters.
required Boolean Yes Specifies whether the service is required for the standard category.
  • true: yes
  • false: no
callType String Yes The call method of the service.
  • ASYNC: asynchronous call
  • SYNC: synchronous call
custom Boolean Yes Specifies whether the service is a custom feature.
  • true: yes
  • false: no

Event data format

The following table lists the parameters that are included in the data format of an event.

Parameter Type Required Description
productKey String Yes The key of the product to which the TSL belongs.
identifier String Yes The identifier of the event. The identifier must be 50 characters in length and can contain uppercase letters, lowercase letters, digits, and underscores (_).
Note The identifier cannot be any of the following words: set, get, post, property, event, time, and value.
eventName String Yes The name of the event. The name can contain Chinese characters, English letters, digits, hyphens (-), underscores (_), and periods (.). It must start with a Chinese character, English letter, or digit. The name must be up to 30 characters in length. A Chinese character is counted as one encoding character.
eventType String Yes The type of the event.
  • INFO_EVENT_TYPE: information
  • ALERT_EVENT_TYPE: alert
  • ERROR_EVENT_TYPE: error
outputdata List No The output parameters of the event. For more information about the data format of an output parameter, see Data formats of input and output parameters.
required Boolean Yes Specifies whether the event is required for the standard category.
  • true: yes
  • false: no
custom Boolean Yes Specifies whether the event is a custom feature.
  • true: yes
  • false: no

Data formats of input and output parameters

The following table lists the parameters that are included in the data format of an input or output parameter. Input or output parameters are specified for a service or event.

Parameter Type Required Description
dataType String Yes The data type of the parameter.

Valid values: ARRAY, STRUCT, INT, FLOAT, DOUBLE, TEXT, DATE, ENUM, and BOOL.

For more information about how to specify parameters based on data types, see the corresponding sections in this topic.

identifier String Yes The identifier of the input parameter. The identifier must be 50 characters in length and can contain uppercase letters, lowercase letters, digits, and underscores (_).
Note The identifier cannot be any of the following words: set, get, post, property, event, time, and value.
name String Yes The name of the parameter. The name can contain Chinese characters, English letters, digits, hyphens (-), underscores (_), and periods (.). It must start with a Chinese character, English letter, or digit. The name must be up to 30 characters in length. A Chinese character is counted as one encoding character.
direction String Yes Indicates whether the parameter is an input parameter or an output parameter.
  • PARAM_INPUT: input parameter
  • PARAM_OUTPUT: output parameter
paraOrder Integer Yes The serial number of the parameter. The serial number starts at 0 and cannot be repeated.
dataSpecs Object No If you set the dataType parameter to any of the following values: INT, FLOAT, DOUBLE, TEXT, DATE, and ARRAY, the data format is included in the dataSpecs parameter.
Note The data format excludes the parameters that are used to define properties, services, and events.
dataSpecsList List No If you set the dataType parameter to any of the following values: ENUM, BOOL, and STRUCT, the data format is included in the dataSpecsList parameter.
Note The data format excludes the parameters that are used to define properties, services, and events.
custom Boolean Yes Specifies whether the parameter belongs to a custom feature.
  • true: yes
  • false: no

INT, FLOAT, and DOUBLE data format

The following table lists the parameters that are included in the data format if the data type of a TSL feature or parameter is set to INT, FLOAT, or DOUBLE.

Parameter Type Required Description
dataType String Yes Valid values: INT, FLOAT, and DOUBLE.
max String Yes The maximum value. Valid values: INT, FLOAT, and DOUBLE.
min String Yes The minimum value. Valid values: INT, FLOAT, and DOUBLE.
step String Yes The step size. Valid values: INT, FLOAT, and DOUBLE.
precise String No The precision of the value. You can specify this parameter when the dataType parameter is set to FLOAT or DOUBLE.
defaultValue String No You specify this parameter to set a default value.
unit String Yes The symbol of the unit.
unitName String Yes The name of the unit.
custom Boolean Yes Specifies whether the TSL feature is a custom feature.
  • true: yes
  • false: no

DATE and TEXT data format

The following table lists the parameters that are included in the data format if the data type of a TSL feature or parameter is set to DATE or TEXT.

Parameter Type Required Description
dataType String Yes Valid values: DATE and TEXT.
length Long Yes The data length. A maximum of 2,048 bytes are allowed. You must specify this parameter if the dataType parameter is set to TEXT.
defaultValue String No You specify this parameter to set a default value.
custom Boolean Yes Specifies whether the TSL feature is a custom feature.
  • true: yes
  • false: no

ARRAY data format

The following table lists the parameters that are included in the data format if the data type of a TSL feature or parameter is set to ARRAY.

Parameter Type Required Description
dataType String Yes The value is set to ARRAY.
size Long Yes The number of elements in the array.
childDataType String Yes The data type of the elements in the array. Valid values: STRUCT, INT, FLOAT, DOUBLE, and TEXT.
dataSpecs Object No If you set the dataType parameter to any of the following values: INT, FLOAT, DOUBLE, TEXT, DATE, and ARRAY, the data format is included in the dataSpecs parameter.
Note The data format excludes the parameters that are used to define properties, services, and events.
dataSpecsList List No If you set the dataType parameter to any of the following values: ENUM, BOOL, and STRUCT, the data format is included in the dataSpecsList parameter.
Note The data format excludes the parameters that are used to define properties, services, and events.
custom Boolean Yes Specifies whether the TSL feature is a custom feature.
  • true: yes
  • false: no

BOOLEAN and ENUM data format

The following table lists the parameters that are included in the data format if the data type of a TSL feature or parameter is set to BOOL or ENUM.

Parameter Type Required Description
dataType String Yes Valid values: BOOL and ENUM.
name String Yes The name of the ENUM value. The name can contain Chinese characters, English letters, digits, underscores (_), and hyphens (-). It must start with a Chinese character, English letter, or digit. The name must be up to 20 characters in length. A Chinese character is counted as one encoding character.
value Integer Yes The value of the enumeration.
custom Boolean Yes Specifies whether the TSL feature is a custom feature.
  • true: yes
  • false: no

STRUCT data format

The following table lists the parameters that are included in the data format if the data type of a TSL feature or parameter is set to STRUCT.

Parameter Type Required Description
dataType String Yes The value is set to STRUCT.
identifier String Yes The identifier of the sub-parameter in the structure. The identifier must be 50 characters in length and can contain uppercase letters, lowercase letters, digits, and underscores (_).
Note The identifier cannot be any of the following words: set, get, post, property, event, time, and value.
name String Yes The name of the sub-parameter in the structure. The name can contain Chinese characters, English letters, digits, hyphens (-), underscores (_), and periods (.). It must start with a Chinese character, English letter, or digit. The name must be up to 30 characters in length. A Chinese character is counted as one encoding character.
childDataType String No The data type of the sub-parameter in the structure.

Valid values: INT, FLOAT, DOUBLE, TEXT, DATE, ENUM, and BOOL.

childName String Yes The name of the sub-parameter in the structure. The name can contain Chinese characters, English letters, digits, hyphens (-), underscores (_), and periods (.). It must start with a Chinese character, English letter, or digit. The name must be up to 30 characters in length. A Chinese character is counted as one encoding character.
dataSpecs Object No

If you set the dataType parameter to any of the following values: INT, FLOAT, DOUBLE, TEXT, DATE, and ARRAY, the data format is included in the dataSpecs parameter.

Note The data format excludes the parameters that are used to define properties, services, and events.
dataSpecsList List No If you set the dataType parameter to any of the following values: ENUM, BOOL, and STRUCT, the data format is included in the dataSpecsList parameter.
Note The data format excludes the parameters that are used to define properties, services, and events.
custom Boolean Yes Specifies whether the TSL feature is a custom feature.
  • true: yes
  • false: no

Verify the ThingModelJson parameter

You can use the json-schema file to verify the input parameters in the ThingModelJson parameter.

The following sample code can be used for verification:

package com.aliyun.iot.thingmodel;

import java.io.InputStream;
import java.util.ArrayList;
import java.util.Arrays;

import org.everit.json.schema.Schema;
import org.everit.json.schema.ValidationException;
import org.everit.json.schema.loader.SchemaLoader;
import org.json.JSONObject;
import org.json.JSONTokener;

/**
 * @author: ***
 * @date: 2020-01-14 15:11
 */
public class ThingModelJsonValidator {

    public static void main(String[] args) throws Exception {

        try (InputStream inputStream = ThingModelJsonValidator.class.getClassLoader().getResourceAsStream(
            "thing-model-schema.json")) {
            JSONObject rawSchema = new JSONObject(new JSONTokener(inputStream));
            Schema schema = SchemaLoader.load(rawSchema);
            long start = System.currentTimeMillis();
            JSONObject object = new JSONObject();
            String jsonStr = "{\n"
                + "\t\t\t\"productKey\": \"a1Q1Yrc****\",\n"
                + "\t\t\t\"name\": \"AlertEvent\",\n"
                + "\t\t\t\"identifier\": \"alarmEvent\",\n"
                + "\t\t\t\"eventName\": \"AlertEvent\",\n"
                + "\t\t\t\"eventType\": \"ALERT_EVENT_TYPE\",\n"
                + "\t\t\t\"outputData\": [\n"
                + "\t\t\t\t{\n"
                + "\t\t\t\t\t\"paraOrder\": 0,\n"
                + "\t\t\t\t\t\"direction\": \"PARAM_OUTPUT\",\n"
                + "\t\t\t\t\t\"dataSpecsList\": [\n"
                + "\t\t\t\t\t\t{\n"
                + "\t\t\t\t\t\t\t\"dataType\": \"ENUM\",\n"
                + "\t\t\t\t\t\t\t\"name\": \"Anti-tamperingAlarm\",\n"
                + "\t\t\t\t\t\t\t\"value\": 0\n"
                + "\t\t\t\t\t\t},\n"
                + "\t\t\t\t\t\t{\n"
                + "\t\t\t\t\t\t\t\"dataType\": \"ENUM\",\n"
                + "\t\t\t\t\t\t\t\"name\": \"CancelAnti-tamperingAlarm\",\n"
                + "\t\t\t\t\t\t\t\"value\": 1\n"
                + "\t\t\t\t\t\t}\n"
                + "\t\t\t\t\t],\n"
                + "\t\t\t\t\t\"dataType\": \"ENUM\",\n"
                + "\t\t\t\t\t\"identifier\": \"alarmType\",\n"
                + "\t\t\t\t\t\"name\": \"AlarmType\",\n"
                + "\t\t\t\t\t\"index\": 0,\n"
                + "\t\t\t\t\t\"custom\": true\n"
                + "\t\t\t\t}\n"
                + "\t\t\t],\n"
                + "\t\t\t\"outputParams\": [\n"
                + "\t\t\t\t{\n"
                + "\t\t\t\t\t\"index\": 0,\n"
                + "\t\t\t\t\t\"identifier\": \"alarmType\"\n"
                + "\t\t\t\t}\n"
                + "\t\t\t],\n"
                + "\t\t\t\"custom\": true\n"
                + "\t\t}";

            object.put("properties", new ArrayList<>());
            object.put("services", new ArrayList<>());
            object.put("events", Arrays.asList(com.alibaba.fastjson.JSONObject.parseObject(jsonStr)));
            object.put("productKey", "a1Q1Yrc****");
            schema.validate(object); // throws a ValidationException if this object is invalid
            //}
            System.out.println(System.currentTimeMillis() - start);
        }
        catch (ValidationException exception) {
            System.out.println(exception);
        }
    }

}

The following section describes the data format that is defined in the json_schema file: 

{
  "id": "http://json-schema.org/draft-04/schema#",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Core schema meta-schema",
  "definitions": {
    "nameDefinition": {
      "type": "string",
      "pattern": "^[\\u4E00-\\u9FA5a-zA-Z0-9][\\u4E00-\\u9FA5a-zA-Z0-9_\\-\\(\\)\\uFF08\\uFF09\\u0020\\s\\.]{0,39}$"
    },
    "identifierDefinition": {
      "type": "string",
      "pattern": "[_a-zA-Z0-9]{1,50}"
    },
    "descriptionDefinition": {
      "type": "string",
      "pattern": ".{1,2048}"
    },
    "rwFlagDefinition": {
      "type": "string",
      "pattern": "(READ_WRITE|READ_ONLY|WRITE_ONLY)"
    },
    "callTypeDefinition": {
      "type": "string",
      "pattern": "(ASYNC|SYNC)"
    },
    "eventTypeDefinition": {
      "type": "string",
      "pattern": "(INFO_EVENT_TYPE|ALERT_EVENT_TYPE|ERROR_EVENT_TYPE)"
    },
    "requiredDefinition": {
      "type": "boolean"
    },
    "customDefinition": {
      "type": "boolean"
    },
    "directionDefinition": {
      "type": "string",
      "pattern": "(PARAM_INPUT|PARAM_OUTPUT)"
    },
    "argumentDefinition": {
      "required": [
        "identifier",
        "name",
        "dataType",
        "custom",
        "direction",
        "paraOrder"
      ],
      "properties": {
        "direction": {
          "$ref": "#/definitions/directionDefinition"
        },
        "paraOrder": {
          "type": "integer"
        },
        "identifier": {
          "$ref": "#/definitions/identifierDefinition"
        },
        "name": {
          "$ref": "#/definitions/nameDefinition"
        },
        "dataType": {
          "$ref": "#/definitions/dataTypeDefinition"
        },
        "description": {
          "$ref": "#/definitions/descriptionDefinition"
        },
        "custom": {
          "$ref": "#/definitions/customDefinition"
        },
        "dataSpecs": {
          "type": "object"
        },
        "dataSpecsList": {
          "type": "array"
        }
      }
    },
    "propertyDefinition": {
      "required": [
        "identifier",
        "name",
        "dataType",
        "productKey",
        "rwFlag",
        "custom",
        "required"
      ],
      "properties": {
        "identifier": {
          "$ref": "#/definitions/identifierDefinition"
        },
        "name": {
          "$ref": "#/definitions/nameDefinition"
        },
        "dataType": {
          "$ref": "#/definitions/dataTypeDefinition"
        },
        "rwFlag": {
          "$ref": "#/definitions/rwFlagDefinition"
        },
        "required": {
          "$ref": "#/definitions/requiredDefinition"
        },
        "description": {
          "$ref": "#/definitions/descriptionDefinition"
        },
        "custom": {
          "$ref": "#/definitions/customDefinition"
        },
        "dataSpecs": {
          "type": "object"
        },
        "dataSpecsList": {
          "type": "array"
        }
      }
    },
    "serviceDefinition": {
      "required": [
        "identifier",
        "serviceName",
        "productKey",
        "callType",
        "custom",
        "required"
      ],
      "properties": {
        "identifier": {
          "$ref": "#/definitions/identifierDefinition"
        },
        "serviceName": {
          "$ref": "#/definitions/nameDefinition"
        },
        "callType": {
          "$ref": "#/definitions/callTypeDefinition"
        },
        "required": {
          "$ref": "#/definitions/requiredDefinition"
        },
        "description": {
          "$ref": "#/definitions/descriptionDefinition"
        },
        "custom": {
          "$ref": "#/definitions/customDefinition"
        },
        "inputParams": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/argumentDefinition"
          }
        },
        "outputParams": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/argumentDefinition"
          }
        }
      }
    },
    "eventDefinition": {
      "required": [
        "identifier",
        "eventName",
        "eventType",
        "productKey",
        "custom",
        "required"
      ],
      "properties": {
        "identifier": {
          "$ref": "#/definitions/identifierDefinition"
        },
        "eventName": {
          "$ref": "#/definitions/nameDefinition"
        },
        "eventType": {
          "$ref": "#/definitions/eventTypeDefinition"
        },
        "required": {
          "$ref": "#/definitions/requiredDefinition"
        },
        "description": {
          "$ref": "#/definitions/descriptionDefinition"
        },
        "custom": {
          "$ref": "#/definitions/customDefinition"
        },
        "outputData": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/argumentDefinition"
          }
        }
      }
    },
    "dataTypeDefinition": {
      "enum": [
        "ARRAY",
        "STRUCT",
        "INT",
        "FLOAT",
        "DOUBLE",
        "TEXT",
        "DATE",
        "ENUM",
        "BOOL"
      ]
    },
    "dataSpecsDefinition": {
      "type": "object",
      "required": [
        "identifier",
        "isStd",
        "dataType",
        "childName",
        "name",
        "childDataType",
        "childSpecsDTO"
      ]
    }
  },
  "type": "object",
  "properties": {
    "productKey": {
      "type": "string"
    },
    "properties": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/propertyDefinition"
      }
    },
    "services": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/serviceDefinition"
      }
    },
    "events": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/eventDefinition"
      }
    }
  }
}