When you call API operations that are related to Thing Specification Language (TSL) models, the request parameters or response parameters may contain the ThingModelJson parameter. The value of this parameter indicates the TSL data structure that is stored in IoT Platform. This TSL data structure is different from the original TSL data structure. All fields in the ThingModelJson parameter are sorted by key in alphabetical order.
For information about the limits of TSL features, see Limits.
Data structure
The data structure of a default TSL module is different from that of a custom TSL module.
- Default TSL module
{ "_ppk":{ "description":"test", "version":"159244410****" } "events":[], "productKey":"al12345****", "properties":[], "services":[], "functionBlocks":[{ "productKey":"al12345****", "functionBlockId":"location0", "functionBlockName":"Location module 0" }] }
Parameter Type Description productKey String The ProductKey of the product to which the TSL model belongs. _ppk String The information about the TSL model version. This parameter consists of the following fields: - version: the version number of the current TSL model. This field is available only for published TSL models.
- description: the description of the current TSL model. This field is available only for published TSL models.
properties List The properties of the product to which the TSL model belongs. For more information about the data structure of the properties parameter, see Data structure of the properties parameter. In each property, you can use the extendConfig parameter to define the extended information about the TSL model. For more information, see Data structure of the extendConfig parameter. If no extended information needs to be defined, you do not need to specify the extendConfig parameter.
services List The services of the product to which the TSL model belongs. For more information about the data structure of the services parameter, see Data structure of the services parameter. In each service, you can use the extendConfig parameter to define the extended information about the TSL model. For more information, see Data structure of the extendConfig parameter. If no extended information needs to be defined, you do not need to specify the extendConfig parameter.
events List The events of the product to which the TSL model belongs. For more information about the data structure of the events parameter, see Data structure of the events parameter. In each event, you can use the extendConfig parameter to define the extended information about the TSL model. For more information, see Data structure of the extendConfig parameter. If no extended information needs to be defined, you do not need to specify the extendConfig parameter.
functionBlocks List The list of custom modules. This parameter is available only when the product contains at least one custom TSL module. This parameter consists of the following fields: - productKey: the ProductKey of the product to which the TSL model belongs.
- functionBlockId: the identifier of the custom TSL module. Each identifier is unique in a product.
- functionBlockName: the name of the custom TSL module.
- Custom TSL module
{ "productKey":"al12345****", "identifier":"location0", "name":"Location module 0", "properties":[], "services":[], "events":[], "description":"" }
The following table describes the parameters of a custom TSL module, excluding those inherited from the default TSL module.
Parameter Type Description identifier String The identifier of the custom TSL module. Each identifier is unique in a product. The identifier must be 1 to 30 characters in length, and can contain letters, digits, and underscores (_).
name String The name of the custom TSL module. The name must be 4 to 30 characters in length, and can contain letters, digits, and underscores (_).
description String The description of the custom TSL module. The description can be up to 100 characters in length.
Data structure of the properties parameter
The following table describes the parameters that are used to define a property.
Parameter | Type | Required | Description |
---|---|---|---|
productKey | String | Yes | The ProductKey of the product to which the TSL model belongs. |
createTs | Long | No | The time when the feature was defined. By default, the value is a 13-digit timestamp. You can specify this parameter. If you do not specify this parameter, IoT Platform generates a timestamp. Features are sorted by timestamp in chronological order. Note For an existing TSL model, its creation time is the time when the TSL model was first modified after it was published. |
identifier | String | Yes | The identifier of the property. The identifier can be up to 50 characters in length and can contain letters, digits, and underscores (_). Note The identifier cannot be one 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 must specify different parameters when different data types are specified. For more information, see the data structure of the corresponding type in this topic. |
name | String | Yes | The name of the property. The name can be up to 30 characters in length and can contain letters, digits, hyphens (-), underscores (_), and periods (.). It must start with a letter or digit. |
rwFlag | String | Yes | The type of the operation that IoT Platform can perform on the property. Valid values:
|
dataSpecs | Object | No | If you set dataType to INT, FLOAT, DOUBLE, TEXT, DATE, or ARRAY, the data specifications are included in the dataSpecs parameter. Note
|
dataSpecsList | List | No | If you set the dataType parameter to ENUM, BOOL, or STRUCT, the data specifications are included in the dataSpecsList parameter. Note
|
required | Boolean | Yes | Specifies whether the property is required for the standard category. Valid values:
|
custom | Boolean | Yes | Specifies whether the TSL feature is a custom feature. Valid values:
|
- Sample value of the dataSpecs parameter if the dataType parameter is set to INT:
{ "dataSpecs": { "custom": true, "dataType": "INT", "defaultValue": "30", "max": "1440", "min": "0", "step": "10", "unit": "min" } }
- Sample value of the dataSpecs parameter if the dataType parameter is set to TEXT:
{ "dataSpecs": { "custom": true, "dataType": "TEXT", "id": 2412127, "length": 2048 } }
- Sample value of the dataSpecs parameter if the dataType parameter is set to ARRAY:
{ "dataSpecs": { "childDataType": "INT", "custom": true, "dataType": "ARRAY", "size": 1 } }
- Sample value of the dataSpecsList parameter if the dataType parameter is set to ENUM:
{ "dataSpecsList": [ { "custom": false, "dataType": "ENUM", "defaultValue": "true", "name": "Open", "value": 1 }, { "custom": false, "dataType": "ENUM", "defaultValue": "false", "name": "Close", "value": 0 } ] }
- Sample value of the dataSpecsList parameter if the dataType parameter is set to STRUCT:
{ "childDataType": "TEXT", "childName": "Card number", "dataSpecs": { "custom": true, "dataType": "TEXT", "length": 128 }, "dataType": "STRUCT", "identifier": "CardNo", "name": "NVR chip information" }
Data structure of the services parameter
The following table describes the parameters that are used to define a service.
Parameter | Type | Required | Description |
---|---|---|---|
productKey | String | Yes | The ProductKey of the product to which the TSL model belongs. |
createTs | Long | No | The time when the feature was defined. By default, the value is a 13-digit timestamp. You can specify this parameter. If you do not specify this parameter, IoT Platform generates a timestamp. Features are sorted by timestamp in chronological order. Note For an existing TSL model, its creation time is the time when the TSL model was first modified after it was published. |
identifier | String | Yes | The identifier of the service. The identifier must be 1 to 50 characters in length and can contain letters, digits, and underscores (_). Note The identifier cannot be one of the following words: set, get, post, property, event, time, and value. |
serviceName | String | Yes | The name of the service. The name must be 1 to 30 characters in length and can contain letters, digits, hyphens (-), underscores (_), and periods (.). It must start with a letter or digit. |
inputParams | List | No | The input parameters of the service. For more information about the data structure, see Data structure of the input and output parameters. |
outputParams | List | No | The output parameters of the service. For more information about the data structure, see Data structure of the input and output parameters. |
required | Boolean | Yes | Specifies whether the service is required for the standard category. Valid values:
|
callType | String | Yes | The method that is used to call the service.
|
custom | Boolean | Yes | Specifies whether the TSL feature is a custom feature. Valid values:
|
Data structure of the events parameter
The following table describes the parameters that are used to define an event.
Parameter | Type | Required | Description |
---|---|---|---|
productKey | String | Yes | The ProductKey of the product to which the TSL model belongs. |
createTs | Long | No | The time when the feature was defined. By default, the value is a 13-digit timestamp. You can specify this parameter. If you do not specify this parameter, IoT Platform generates a timestamp. Features are sorted by timestamp in chronological order. Note For an existing TSL model, its creation time is the time when the TSL model was first modified after it was published. |
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 one of the following words: set, get, post, property, event, time, and value. |
eventName | String | Yes | The list of one or more event names. The name must be 1 to 30 characters in length, and can contain letters, digits, hyphens (-), underscores (_), and periods (.). The name must start with a letter or digit. |
eventType | String | Yes | The type of the event. Valid values:
|
outputdata | List | No | The output parameters of the event. For more information about the data structure, see Data structure of the input and output parameters. |
required | Boolean | Yes | Specifies whether the event is required for the standard category. Valid values:
|
custom | Boolean | Yes | Specifies whether the TSL feature is a custom feature. Valid values:
|
Data structure of the input and output parameters
The following table describes the parameters that are used to define the input and output parameters of a service or an event.
Parameter | Type | Required | Description |
---|---|---|---|
dataType | String | Yes | The data type of the parameter value. Valid values: ARRAY, STRUCT, INT, FLOAT, DOUBLE, TEXT, DATE, ENUM, and BOOL. For more information, see the data structure of the corresponding type in this topic. |
identifier | String | Yes | The identifier of the parameter. The identifier must be 1 to 50 characters in length and can contain letters, digits, and underscores (_). Note The identifier cannot be one of the following words: set, get, post, property, event, time, and value. |
name | String | Yes | The name of the request parameter. The name must be 1 to 30 characters in length and can contain letters, digits, hyphens (-), underscores (_), and periods (.). It must start with a letter or digit. |
direction | String | Yes | Specifies whether the parameter is an input parameter or output parameter. Valid values:
|
paraOrder | Integer | Yes | The serial number of the parameter. The serial number starts from 0 and must be unique. |
dataSpecs | Object | No | If you set the dataType parameter to INT, FLOAT, DOUBLE, TEXT, DATE, or ARRAY, the data specifications are included in the dataSpecs parameter. Note
|
dataSpecsList | List | No | If you set the dataType parameter to ENUM, BOOL, or STRUCT, the data specifications are included in the dataSpecsList parameter. Note
|
custom | Boolean | Yes | Specifies whether the parameter belongs to a custom TSL feature. Valid values:
|
Data structure of the INT, FLOAT, or DOUBLE type
The following table describes the parameters that are used to define the data of the INT, FLOAT, and DOUBLE types.
Parameter | Type | Required | Description |
---|---|---|---|
dataType | String | Yes | The type of the data. Valid values: INT, FLOAT, and DOUBLE. |
max | String | Yes | The maximum value of the parameter. The maximum value is of the INT, FLOAT, or DOUBLE type, as specified by the dataType parameter. The value of the max parameter must be converted to the data of the STRING type. For example, if the dataType parameter is set to INT, the value of 200 must be expressed as |
min | String | Yes | The minimum value of the parameter. The minimum value is of the INT, FLOAT, or DOUBLE type, as specified by the dataType parameter. The value of the step parameter must be converted to the data of the STRING type. For more information, see the description of the max parameter. |
step | String | Yes | The step size, which indicates the increment of each data change. The step size is of the INT, FLOAT, or DOUBLE type, as specified by the dataType parameter. The value of the step parameter must be converted to the data of the STRING type. For more information, see the description of the max parameter. |
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 can 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. Valid values:
|
Data structure of the DATE or TEXT type
The following table describes the parameters that are used to define the data of the DATE and TEXT types.
Parameter | Type | Required | Description |
---|---|---|---|
dataType | String | Yes | The type of the data. Valid values: DATE and TEXT. |
length | Long | Yes | The length of the data. Maximum value: 2048. Unit: bytes. You must specify this parameter if the dataType parameter is set to TEXT. |
defaultValue | String | No | You can specify this parameter to set a default value. |
custom | Boolean | Yes | Specifies whether the TSL feature is a custom feature. Valid values:
|
Data structure of the ARRAY type
The following table describes the parameters that are used to define the data of the ARRAY type.
Parameter | Type | Required | Description |
---|---|---|---|
dataType | String | Yes | The type of the data. Set the value 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 INT, FLOAT, DOUBLE, TEXT, DATE, or ARRAY, the data specifications are included in the dataSpecs parameter. Note
|
dataSpecsList | List | No | If you set the dataType parameter to ENUM, BOOL, or STRUCT, the data specifications are included in the dataSpecsList parameter. Note
|
custom | Boolean | Yes | Specifies whether the TSL feature is a custom feature. Valid values:
|
Data structure of the ENUM or BOOL type
The following table describes the parameters that are used to define the data of the BOOL and ENUM types.
Parameter | Type | Required | Description |
---|---|---|---|
dataType | String | Yes | The type of the data. Valid values: BOOL and ENUM. |
name | String | Yes | The name of the ENUM item. The name must be 1 to 20 characters in length and can contain letters, digits, underscores (_), and hyphens (-). The name must start with a letter or digit. |
value | Integer | Yes | The value of the ENUM item. |
custom | Boolean | Yes | Specifies whether the TSL feature is a custom feature. Valid values:
|
Data structure of the STRUCT type
The following table describes the parameters that are used to define the data of the STRUCT type.
- The childSpecsDTO and childEnumSpecsDTO that were used in the previous versions of APIs have been phased out. Therefore, no description is provided for these parameters in this section. When you call API operations, you do not need to specify these two parameters. We recommend that you use the dataSpecsList parameter in replacement of the two parameters.
- If the data of the ARRAY type and the data of the STRUCT type are nested with each other, up to two layers of recursive nesting are supported.
Parameter | Type | Required | Description |
---|---|---|---|
dataType | String | Yes | The type of the data. Set the value to STRUCT. |
identifier | String | Yes | The identifier of the sub-parameter in the struct. The identifier can be up to 50 characters in length and can contain letters, digits, and underscores (_). Note The identifier cannot be one of the following words: set, get, post, property, event, time, and value. |
name | String | Yes | The name of the sub-parameter in the struct. The name can be up to 30 characters in length and can contain letters, digits, hyphens (-), underscores (_), and periods (.). It must start with a letter or digit. Note The definition of the parameter is the same as the definition of the childName parameter. This parameter is not used. |
childDataType | String | No | The data type of the sub-parameter in the struct. Valid values: INT, FLOAT, DOUBLE, TEXT, DATE, ENUM, and BOOL. |
childName | String | Yes | The name of the sub-parameter in the struct. The name can be up to 30 characters in length and can contain letters, digits, hyphens (-), underscores (_), and periods (.). It must start with a letter or digit. |
dataSpecs | Object | No | If you set the dataType parameter to INT, FLOAT, DOUBLE, TEXT, DATE, or ARRAY, the data specifications are included in the dataSpecs parameter. Note
|
dataSpecsList | List | No | If you set the dataType parameter to ENUM, BOOL, or STRUCT, the data specifications are included in the dataSpecsList parameter. Note
|
custom | Boolean | Yes | Specifies whether the TSL feature is a custom feature. Valid values:
|
Data structure of the extendConfig parameter
In each property, event, and service, you can use the extendConfig parameter to define the extended information about the TSL model. The extended information indicates the mapping between the connection protocol and the standard TSL model of the device.
If Modbus, OPC UA, or a custom protocol is used as the gateway connection protocol of a device, you can define the extended information about the device. Different types of extended information have different data specifications.
Modbus type
If Modbus is used as the gateway connection protocol of a device, you can define the extended information only about the properties.
{
"identifier":"extend1",
"writeFunctionCode":0,
"writeOnly":0,
"registerAddress":"0xFE",
"operateType":"coilStatus",
"scaling":0.1,
"pollingTime":1000,
"trigger":1,
"bitMask":128,
"originalDataType":{
"type":"uint64",
"specs":{
"swap":0,
"reverseRegister":0}
}
}
Parameter | Type | Description |
---|---|---|
identifier | String | The identifier of the property. The identifier must be unique in a product. |
registerAddress | String | The address of the register. The address must start with 0x . Valid values: 0x0 to 0xFFFF. Example: 0xFE. |
operateType | String | The type of the operation. Valid values:
|
writeFunctionCode | Integer | The read and write operations. The value varies based on the value of the operateType parameter.
|
writeOnly | Integer | Specifies whether the operation is write-only. Valid values:
|
scaling | Number | The scaling factor. The value cannot be 0. This parameter is unavailable for data of the STRING and BOOLEAN types. |
pollingTime | Integer | The interval of the collection. Unit: ms. You do not need to specify this parameter. The specified collection interval of the device is used. |
trigger | Integer | The method to submit data. Valid values: 1 and 2. The value of 1 indicates that data is submitted at a specific time. The value of 2 indicates that data is submitted when changes occur. |
bitMask | Integer | The mask. Valid values: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, and 32768. This parameter is specific to data of the BOOLEAN type. |
originalDataType | Object | The description of the original data type. |
type | String | The type of the original data. The type must be one of the following basic data types: INT16, UINT16, INT32, UINT32, INT64, UINT64, FLOAT, DOUBLE, STRING, BOOLEAN, and customized (hexadecimal data that is returned in big-endian order). |
specs | Object | The parameters that are specific to some data types. |
registerCount | Integer | The number of registers. This parameter is specific to data of the STRING and customized types. |
swap | Integer | This parameters is specific to data of all types except for the STRING and customized types. Specifies whether to switch the high byte and low byte in the register. If so, the first and last 8 bits of the 16-bit integer in the register are swapped. Valid values:
|
reverseRegister | Integer | This parameters is specific to data of all types except for the STRING and customized types. Specifies whether to switch the high byte and low byte in the register. If so, the first and last 16 bits of the 32-bit integer in the register are swapped. Valid values:
|
OPC UA type
If OPC UA is used as the gateway connection protocol of a device, you can define the extended information about the properties, services, and events.
{
"identifier":"extend2",
"displayName":"Action",
"inputData":[
{
"identifier":"xxxx",
"index":1
},
{
"identifier":"xxxx",
"index":2
}
],
"outputData":[
{
"identifier":"xxxx",
"index":1
},
{
"identifier":"xxxx",
"index":2
}
]
}
Parameter | Type | Description |
---|---|---|
identifier | String | The identifier of the property, service, or event. The identifier must be unique in a product. |
displayName | String | You must specify the displayName parameter for a property or an event. You do not need to specify the displayName parameter for a service. |
inputData | List | The input data. |
outputData | List | The output data. |
identifier | String | The identifier of the input data or output data. The identifier must be unique in a product. |
index | Integer | The index. The index must be unique in both the inputData and outputData parameters. |
Custom type
If a custom protocol is used as the gateway connection protocol of a device, you can define the extended information about the properties, services, and events.
{
"identifier":"xxx",
"customize":{}
}
Parameter | Type | Description |
---|---|---|
identifier | String | The identifier of the property, service, or event. It must be unique in a product. |
customize | Object | The custom JSON file. |
Verify the ThingModelJson parameter
You can use the json-schema file to verify the input parameters in the ThingModelJson parameter.
For more information, see schema.json.
Example of verifying the ThingModelJson parameter
- Add the following dependency to the Maven project to download the json-schema library:
<dependency> <groupId>com.github.everit-org.json-schema</groupId> <artifactId>org.everit.json.schema</artifactId> <version>1.11.0</version> </dependency>
- Sample code:
package com.aliyun.iot.thingmodel; import java.io.InputStream; import java.net.URL; 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 = new URL("https://iotx-thing-model-schema.oss-ap-southeast-1.aliyuncs.com/schema.json").openStream()) { 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\": \"Alert event\",\n" + "\t\t\t\"identifier\": \"alarmEvent\",\n" + "\t\t\t\"eventName\": \"Alert event\",\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-detachment alert\",\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\": \"Anti-detachment alert\",\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\": \"Alert type\",\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); } } }
Specify the ThingModelJson parameter
The section describes how to use the Visual Studio Code tool to specify the ThingModelJson parameter.
- Visit Visual Studio Code official website to download and install the latest version of the Visual Studio Code tool.
- Open Visual Studio Code, click the button in the lower left corner, and then select Settings.
- On the User Settings tab, choose . Click Edit in settings.json under Schemas, and then enter and save the following content.
"json.schemas": [{ "fileMatch": ["/.json"], "url": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json" }]
Then, you can specify the ThingModelJson parameter as prompted.