The ThingModelJson parameter, used in certain TSL model API requests and responses, represents how IoT Platform stores TSL model feature definitions internally. This structure differs from the TSL data structure, and all fields are sorted alphabetically by key.
For limits on TSL feature definitions for products and devices, see TSL Feature Definition Limits for Products and Devices.
Data structure
Default and custom TSL modules have different data structures.
- 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 version information of the TSL model, containing the following fields: - version: The version number of the TSL model. This parameter is returned only for published TSL models.
- description: The description of the default TSL module version. This parameter is returned only for published TSL models.
properties List The list of properties in the TSL model. For more information about the property data structure, see Property data structure specification. Use extendConfig in each property data structure to define extended information. For more information, see extendConfig data structure specification. If a property has no extended information, you do not need to pass extendConfig.
services List The list of services in the TSL model. For more information about the service data structure, see Service data format specification. Use extendConfig in each service data structure to define extended information. For more information, see extendConfig data structure specification. If a service has no extended information, you do not need to pass extendConfig.
events List The list of events in the TSL model. For more information about the event data structure, see Event data format specification. Use extendConfig in each event data structure to define extended information. For more information, see extendConfig data structure specifications. If an event does not have extended information, you do not need to pass extendConfig.
functionBlocks List The list of custom TSL modules. Included only if the product has custom modules. Contains the following fields: - productKey: The productKey of the product to which the TSL model belongs.
- functionBlockId: The unique identifier for the custom TSL module within 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 lists the basic parameters of a custom TSL module. For other parameters, see the default TSL module descriptions.
Parameter Type Description identifier String The unique identifier for the custom TSL module within a product. The identifier can be up to 30 characters in length and can contain uppercase letters, lowercase 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 Chinese characters, Japanese characters, English letters, digits, and underscores (_). A Chinese or Japanese character counts as one character.
description String A description of the module, with a maximum length of 100 characters.
Property data structure
The following table lists the parameters for defining a property.
| Parameter | Type | Required | Description |
| productKey | String | Yes | The ProductKey of the product to which the TSL model belongs. |
| createTs | Long | No | The feature's creation time, as a 13-digit timestamp. If you do not specify this parameter, the system generates one. Features are sorted by this timestamp in ascending order. Note For an existing TSL model, the creation time is the time when the TSL model was first modified after it was published. |
| identifier | String | Yes | The property's unique identifier. It must be up to 50 characters long and can contain uppercase letters, lowercase letters, digits, and underscores (_). Note The identifier cannot be a reserved keyword, such as set, get, post, property, event, time, or value. |
| dataType | String | Yes | The property's data type. Valid values: ARRAY, STRUCT, INT, FLOAT, DOUBLE, TEXT, DATE, ENUM, and BOOL. The parameters that you must specify vary based on the data type. For more information, see the data specifications for each data type in this topic. |
| name | String | Yes | The property's display name. The name can be up to 30 characters long and can contain Chinese characters, uppercase letters, lowercase letters, digits, hyphens (-), underscores (_), and periods (.). It must start with a Chinese character, a letter, or a digit. A Chinese character is counted as one character. |
| rwFlag | String | Yes | Whether the property is read-only or read-write in IoT Platform.
|
| dataSpecs | Object | No | If dataType is set to INT, FLOAT, DOUBLE, TEXT, DATE, or ARRAY, the data specifications are stored in the dataSpecs parameter. For examples, see the code blocks below this table. Note
|
| dataSpecsList | List | No | If dataType is set to ENUM, BOOL, or STRUCT, the data specifications are stored in the dataSpecsList parameter. For examples, see the code blocks below this table. Note
|
| required | Boolean | Yes | Specifies whether the property is required for a standard category.
|
| custom | Boolean | Yes | Specifies whether this is a custom feature.
|
- Example of dataSpecs when dataType is INT:
{ "dataSpecs": { "custom": true, "dataType": "INT", "defaultValue": "30", "max": "1440", "min": "0", "step": "10", "unit": "min" } } - Example of dataSpecs when dataType is TEXT:
{ "dataSpecs": { "custom": true, "dataType": "TEXT", "id": 2412127, "length": 2048 } } - Example of dataSpecs when dataType is ARRAY:
{ "dataSpecs": { "childDataType": "INT", "custom": true, "dataType": "ARRAY", "size": 1 } } - Example of dataSpecsList when dataType is ENUM:
{ "dataSpecsList": [ { "custom": false, "dataType": "ENUM", "defaultValue": "true", "name": "Open", "value": 1 }, { "custom": false, "dataType": "ENUM", "defaultValue": "false", "name": "Close", "value": 0 } ] } - Example of an item in dataSpecsList when dataType is STRUCT:
{ "childDataType": "TEXT", "childName": "Card number", "dataSpecs": { "custom": true, "dataType": "TEXT", "length": 128 }, "dataType": "STRUCT", "identifier": "CardNo", "name": "NVR chip information" }
Service data format
The following table lists the parameters for defining a service.
| Parameter | Type | Required | Description |
| productKey | String | Yes | The ProductKey of the product that contains the TSL model. |
|
createTs
|
Long
|
No
|
The feature's creation time, as a 13-digit timestamp. If you do not specify this parameter, the system generates one. Features are sorted by this timestamp in ascending order.
Note For an existing TSL model, the creation time is the time when the TSL model was first modified after it was published. |
| identifier | String | Yes | The service identifier can be up to 50 characters and contain uppercase letters, lowercase letters, digits, and underscores (_). Note The identifier cannot be a reserved keyword, such as set, get, post, property, event, time, or value. |
| serviceName | String | Yes | The service name can be up to 30 characters and can contain Chinese characters, uppercase and lowercase letters, digits, hyphens (-), underscores (_), and periods (.). It must start with a Chinese character, a letter, or a digit. Each Chinese character counts as one character. |
| inputParams | List | No | A list of input parameters. For details on the data structure, see Data structure of the input and output parameters. |
| outputParams | List | No | A list of output parameters. For details on the data structure, see Data structure of the input and output parameters. |
| required | Boolean | Yes | Specifies whether the service is required for a standard category.
|
| callType | String | Yes | The call type of the service.
|
| custom | Boolean | Yes | Specifies whether this is a custom feature.
|
Event data format
The following table lists the parameters for defining an event.
| Parameter | Type | Required | Description |
| productKey | String | Yes | The ProductKey of the product that contains the TSL model. |
|
createTs
|
Long
|
No
|
The feature's creation time, as a 13-digit timestamp. If you do not specify this parameter, the system generates one. Features are sorted by this timestamp in ascending order.
Note For an existing TSL model, the creation time is the time when the TSL model was first modified after it was published. |
| identifier | String | Yes | The event identifier. It can be up to 50 characters long and can contain uppercase letters, lowercase letters, digits, and underscores (_). Note The identifier cannot be a reserved keyword, such as set, get, post, property, event, time, or value. |
| eventName | String | Yes | The event name. The name must be up to 30 characters long and start with a Chinese character, a letter, or a digit. It can contain Chinese characters, uppercase letters, lowercase letters, digits, hyphens (-), underscores (_), and periods (.). Each Chinese character is counted as one character. |
| eventType | String | Yes | The event type. Valid values:
|
| outputdata | List | No | The event's output parameters. For details on the data structure, see Data structure of the input and output parameters. |
| required | Boolean | Yes | Whether this is a required event for a standard category. Valid values:
|
| custom | Boolean | Yes | Whether this is a custom feature. Valid values:
|
Input and output parameter structure
The following table lists the fields for defining input and output parameters of a service or event.
| Parameter | Type | Required | Description |
| dataType | String | Yes | The parameter's data type. Valid values: ARRAY, STRUCT, INT, FLOAT, DOUBLE, TEXT, DATE, ENUM, and BOOL. For the data specifications of each data type, see the corresponding sections in this topic. |
| identifier | String | Yes | A unique identifier for the parameter. It can be up to 50 characters long and can contain uppercase and lowercase letters, digits, and the underscore (_) character. Note The identifier cannot be a reserved keyword, such as set, get, post, property, event, time, or value. |
| name | String | Yes | The display name of the parameter. It can be up to 30 characters in length and can contain Chinese characters, uppercase letters, lowercase letters, digits, hyphens (-), underscores (_), and periods (.). The name must start with a Chinese character, a letter, or a digit. Each Chinese character counts as a single character. |
| direction | String | Yes | Indicates whether the parameter is an input parameter or an output parameter.
|
| paraOrder | Integer | Yes | The unique, zero-based sequence number of the parameter. |
| dataSpecs | Object | No | If the dataType is a simple type such as INT, FLOAT, DOUBLE, TEXT, DATE, or BOOL, the data specifications are stored in the dataSpecs parameter. Note
|
| dataSpecsList | List | No | If the dataType is a complex type such as ENUM, ARRAY, or STRUCT, the data specifications are stored in the dataSpecsList parameter. Note
|
| custom | Boolean | Yes | Indicates whether the parameter belongs to a custom TSL feature.
|
INT, FLOAT, and DOUBLE data structure
If a feature or parameter has a data type of INT, FLOAT, or DOUBLE, its data structure includes the following parameters.
| Parameter | Type | Required | Description |
| dataType | String | Yes | The data type. Valid values: INT, FLOAT, or DOUBLE. |
| max | String | Yes | The maximum value. This value must be of the type specified in the dataType parameter. The value must be passed as a string. For example, if dataType is INT, use |
| min | String | Yes | The minimum value. This value must be of the type specified in the dataType parameter. The value must be passed as a string. For more information, see the description for max. |
| step | String | Yes | The step size, which is the incremental change for the value. This value must be of the type specified in the dataType parameter. The value must be passed as a string. For more information, see the description for max. |
| precise | String | No | The precision. This parameter is used only for the FLOAT and DOUBLE data types. |
| defaultValue | String | No | The default value for the parameter. |
| unit | String | Yes | The unit symbol. |
| unitName | String | Yes | The unit name. |
| custom | Boolean | Yes | Indicates whether this is a custom feature.
|
DATE and TEXT data structure
The data structure for the DATE and TEXT data types includes the following parameters.
| Parameter | Type | Required | Description |
| dataType | String | Yes | The data type. Valid values are DATE or TEXT. |
| length | Long | Yes | The maximum data length is 2,048 bytes. This parameter is required if dataType is set to TEXT. |
| defaultValue | String | No | The default value. |
| custom | Boolean | Yes | Indicates if this is a custom feature.
|
ARRAY data specification
When the data type of a feature or parameter is ARRAY, the data specification includes the following parameters.
| Parameter | Type | Required | Description |
| dataType | String | Yes | The value must be 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, or TEXT. |
| dataSpecs | Object | No | If the childDataType is a non-list type such as INT, FLOAT, DOUBLE, TEXT, DATE, or ARRAY, use this dataSpecs parameter to define the data specification. Note
|
| dataSpecsList | List | No | If the childDataType is a list type such as ENUM, BOOL, or STRUCT, use this dataSpecsList parameter to define the data specification. Note
|
| custom | Boolean | Yes | Indicates whether the feature is custom.
|
ENUM and BOOL types
If a feature or parameter is of type BOOL or ENUM, its data structure includes the following parameters.
| Parameter | Type | Required | Description |
| dataType | String | Yes | The value must be BOOL or ENUM. |
| name | String | Yes | The name of the ENUM item. The name can be up to 20 characters long and must start with a Chinese character, an English letter, or a digit. It can contain Chinese characters, English letters, digits, underscores (_), and hyphens (-). Each Chinese character counts as a single character. |
| value | Integer | Yes | The enum value. |
| custom | Boolean | Yes | Specifies whether this is a custom feature.
|
Struct data structure
When the data type of a feature or parameter is struct, its data structure includes the following parameters.
- The childSpecsDTO and childEnumSpecsDTO parameters are deprecated. This does not affect existing API calls. For new calls, do not pass these parameters. Use the dataSpecsList parameter instead.
- When array and struct data types are nested, up to two levels of recursive nesting (parent and child) are supported.
| Parameter | Type | Required | Description |
| dataType | String | Yes | The value must be struct. |
| identifier | String | Yes | The identifier of the sub-parameter in the struct. It can contain uppercase letters, lowercase letters, digits, and underscores (_). The maximum length is 50 characters. Note The identifier cannot be any of the following reserved words: set, get, post, property, event, time, or value. |
| name | String | Yes | The name of the sub-parameter in the struct. The name must start with a Chinese character, a letter, or a digit. It can contain Chinese characters, uppercase letters, lowercase letters, digits, hyphens (-), underscores (_), and periods (.). The maximum length is 30 characters. Each Chinese character counts as a single character. Note childNameThis parameter has the same definition as and is not currently used. |
| childDataType | String | No | The data type of the sub-parameter in the struct. Valid values: INT, FLOAT, DOUBLE, TEXT, DATE, ENUM, BOOL. |
| childName | String | Yes | The name of the sub-parameter in the struct. The name must start with a Chinese character, a letter, or a digit. It can contain Chinese characters, uppercase letters, lowercase letters, digits, hyphens (-), underscores (_), and periods (.). The maximum length is 30 characters. Each Chinese character counts as a single character. |
| dataSpecs | Object | No |
Data specifications for non-list data types (dataType) such as INT, FLOAT, DOUBLE, TEXT, DATE, and ARRAY are stored in dataSpecs. Note
|
| dataSpecsList | List | No | dataTypeENUMBOOLSTRUCTdataSpecsListIf the of a sub-parameter is a list type (such as , , or ), its data specifications are stored in the parameter. Note
|
| custom | Boolean | Yes | Specifies whether this is a custom feature.
|
extendConfig data structure
In the data structure of each property, event, or service, use extendConfig to define extended information that maps device communication protocols to the standard TSL model.
IoT Platform supports extended information for devices using Modbus, OPC UA, or custom gateway protocols. Data specifications differ by protocol:
Modbus type
Modbus supports extended information for properties only.
extendConfig. The actual parameters depend on your use case.{
"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 | A unique identifier for the property within the product. |
| registerAddress | String | The register address. The value must start with 0x and be within the 0x0 to 0xFFFF range. For example, 0xFE. |
| operateType | String | The operation type. Valid values include:
|
| writeFunctionCode | Integer | The function code for write operations. Valid values depend on the specified operateType.
|
| writeOnly | Integer | Whether the operation is write-only.
|
| scaling | Number | The scaling factor. The value cannot be 0. This parameter is not applicable to string or bool data types. |
| pollingTime | Integer | The collection interval, in milliseconds (ms). If this parameter is not specified, the device's default collection interval is used. |
| trigger | Integer | The data reporting method. 1: Reports data periodically. 2: Reports data on change. |
| bitMask | Integer | A parameter specific to the bool data type. The mask. Valid values: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, and 32768. These values correspond to 1<<(0 to 15). |
| originalDataType | Object | The original data type. |
| type | String | The original data type. The value must be one of the following basic types: int16, uint16, int32, uint32, int64, uint64, float, double, string, bool, or custom data (returns hex data in big-endian order). |
| specs | Object | Parameters specific to certain data types. |
| registerCount | Integer | A parameter specific to string and custom data types. The number of registers. |
| swap | Integer | A parameter for all data types except string and custom data. Specifies whether to swap the high and low bytes within a 16-bit register (for example, byte1byte2 becomes byte2byte1).
|
| reverseRegister | Integer | A parameter for all data types except string and custom data. Specifies whether to reverse the order of 16-bit registers within 32-bit data (for example, byte1byte2byte3byte4 becomes byte3byte4byte1byte2).
|
OPC UA type
OPC UA supports extended information for 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 | A unique identifier for the property, service, or event within a product. |
| displayName | String | The display name. This parameter is required for properties and events but is optional for services. |
| inputData | List | The input data parameters. |
| outputData | List | The output data parameters. |
| identifier | String | A unique identifier for an input or output parameter within the product. |
| index | Integer | A unique index for the parameter within its parent list (inputData or outputData). |
Custom type
The custom type supports extended information for properties, services, and events.
{
"identifier":"xxx",
"customize":{}
}
| Parameter | Type | Description |
| identifier | String | A unique identifier for the property, service, or event within a product. |
| customize | Object | Custom, user-defined data in a JSON object format. |
Validation
You can use json-schema to validate the input parameters in ThingModelJson.
For the schema definition, see schema.json.
The following example shows how to perform validation:
- To download the json-schema library, add the following dependency to your Maven project.
<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 resolved\",\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); } } }
Writing ThingModelJson
Use Visual Studio Code to write ThingModelJson with auto-completion support.
- Go to the Visual Studio Code official website to download and install the latest version of Visual Studio Code.
- Open Visual Studio Code, click the
button in the lower-left corner, and select Settings. - On the User Settings tab, choose . Under Schemas, click Edit in settings.json, add the following configuration, and save the file.
"json.schemas": [{ "fileMatch": ["/.json"], "url": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json" }]After you save the configuration, auto-completion prompts appear as you define a Thing Model.
"$schema": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json" "" events functionBlockId functionBlockName functionBlocks properties services