物联平台的JSON格式的TSL（Thing Specification Language）介绍

参考资料

TSL 最初并非由国际标准组织（如 ISO/IEC 或 IEEE）定义，而是由阿里云（Alibaba Cloud）主导提出并实现的一种事实标准（de facto standard）。

最早出现在阿里云物联网平台（Aliyun IoT Platform）的《物模型 TSL 规范》文档中。

后续被大量中国物联网平台借鉴（例如华为 OceanConnect、百度天工、腾讯连连、涂鸦等），形成业界通用的 JSON 结构模板。

该规范的思想与国际标准 W3C WoT (Web of Things) Thing Description (TD) 有相似之处，但并非相同标准。

对比项	阿里云 TSL	W3C WoT Thing Description
主导组织	阿里云 (Alibaba Cloud)	W3C Web of Things 工作组
数据格式	JSON	JSON-LD（带语义标注）
功能分类	属性（properties）、服务（services）、事件（events）	属性（properties）、动作（actions）、事件（events）
标准地位	企业事实标准	国际标准 (W3C Recommendation)
目标	云平台设备建模与管理	跨平台设备语义互操作

目前，阿里云的 TSL 在国内物联网平台中应用最广；
而 W3C WoT TD 是国际标准化方向，逐渐被一些跨平台 IoT 框架采纳。

一、物模型定义

物模型指将物理空间中的实体数字化，并在云端构建的该实体的数据模型，用于描述实体的功能。下面介绍物模型相关概念和使用方法。
物模型TSL（Thing Specification Language）是一个JSON格式的文件。它是物理空间中的实体，如传感器、车载装置、楼宇、工厂等在云端的数字化表示，从属性、服务和事件三个维度，分别描述了该实体是什么、能做什么、可以对外提供哪些信息。定义了物模型的这三个维度，即完成了产品功能的定义。
物模型将产品功能类型分为三类：属性(properties),功能(function),事件(event)。

功能类型	说明
属性（Property）	一般用于描述设备运行时的状态，如环境监测设备所读取的当前环境温度等。属性支持GET和SET请求方式。应用系统可发起对属性的读取和设置请求。
服务（Service）	设备可被外部调用的能力或方法，可设置输入参数和输出参数。相比于属性，服务可通过一条指令实现更复杂的业务逻辑，如执行某项特定的任务。
事件（Event）	设备运行时的事件。事件一般包含需要被外部感知和处理的通知信息，可包含多个输出参数。如，某项任务完成的信息，或者设备发生故障或告警时的温度等，事件可以被订阅和推送。

二、物模型与实例的关系

物模型是物理世界的实体东西的一个抽象，是进行数字化描述后，用于数字世界的数字模型。抽象就是要提取出产品的共同特征，形成模型。以智能灯为例，不同的灯，尽管规格不同，但它们的属性是相似，比如都有开关状态的属性，功能逻辑也相仿。我们可以将这些特征标准化，形成智能灯的物模型。反过来，物模型也规约了设备的功能。新增加的设备，如果是同一类型的，在设计、研发中，会遵循相同的功能定义，有相同的特征，实现相同的服务。比如，灯都应该有“开”和“关”两种状态。

三、TSL的定义

结构：

{
 "id":"设备ID",
 "name":"设备名称",
 "properties":[...属性],
 "functions":[...功能],
 "events":[...事件]
}

属性：

{
"id": "cpu_usage", //属性标识
"name": "CPU使用率",
"valueType": {   //值类型
  "type": "double", //类型标识,见类型表
  "maxValue":100,
  "minValue":0,
  "unit":"percent",     //单位
  "expands":{"key1":"value1"} //其他自定义拓展定义
},
"expands":{"key1":"value1"} //其他自定义拓展定义
}

功能：

{
"id": "playVoice", //功能标识
"name": "播放声音", //名称
"inputs": [  //输入参数
  {
    "id": "text",
    "name": "文字内容",
    "valueType": { //参数类型
      "type": "string"
    },
    "expands":{"key1":"value1"} //其他自定义拓展定义
  }
],
"output": { //输出
  "type": "boolean" //输出类型
},
"expands":{"key1":"value1"} //其他自定义拓展定义
}

事件

{
"id": "fire_alarm", //事件标识
"name": "火警",
"valueType": {
  "type": "object",  //对象(结构体)类型
  "properties": [    //对象属性(结构与属性定义相同)
    {
      "id": "location",
      "name": "地点",
      "valueType": {
        "type": "string"
      }
    },
    {
      "id": "lng",
      "name": "经度",
      "valueType": {
        "type": "double"
      },
      "expands":{"gis":"lng"} //其他自定义拓展定义
    },
    {
      "id": "lat",
      "name": "纬度",
      "valueType": {
        "type": "double"
      },
       "expands":{"gis":"lat"} //其他自定义拓展定义
    }
  ]
},
"expands":{"key1":"value1"} //其他自定义拓展定义
}

一个完整的物模型：

{
    "schema": "物模型结构定义的访问URL",
    "profile": {
        "productKey": "产品ProductKey"
    },
    "properties": [
        {
            "identifier": "属性唯一标识符（产品下唯一）",
            "name": "属性名称",
            "accessMode": "属性读写类型：只读（r）或读写（rw）。",
            "required": "是否是标准功能的必选属性",
            "dataType": {
                "type": "属性类型: int（原生）、float（原生）、double（原生）、text（原生）、date（String类型UTC毫秒）、bool（0或1的int类型）、enum（int类型，枚举项定义方法与bool类型定义0和1的值方法相同）、struct（结构体类型，可包含前面7种类型，下面使用"specs":[{}]描述包含的对象）、array（数组类型，支持int、double、float、text、struct）",
                "specs": {
                    "min": "参数最小值（int、float、double类型特有）",
                    "max": "参数最大值（int、float、double类型特有）",
                    "unit": "属性单位（int、float、double类型特有，非必填）",
                    "unitName": "单位名称（int、float、double类型特有，非必填）",
                    "size": "数组元素的个数，最大512（array类型特有）。",
                    "step": "步长（text、enum类型无此参数）",
                    "length": "数据长度，最大10240（text类型特有）。",
                    "0": "0的值（bool类型特有）",
                    "1": "1的值（bool类型特有）",
                    "item": {
                        "type": "数组元素的类型（array类型特有）"
                    }
                }
            }
        }
    ],
    "events": [
        {
            "identifier": "事件唯一标识符（产品下唯一，其中post是默认生成的属性上报事件。）",
            "name": "事件名称",
            "desc": "事件描述",
            "type": "事件类型（info、alert、error）",
            "required": "是否是标准功能的必选事件",
            "outputData": [
                {
                    "identifier": "参数唯一标识符",
                    "name": "参数名称",
                    "dataType": {
                        "type": "属性类型: int（原生）、float（原生）、double（原生）、text（原生）、date（String类型UTC毫秒）、bool（0或1的int类型）、enum（int类型，枚举项定义方法与bool类型定义0和1的值方法相同）、struct（结构体类型，可包含前面7种类型，下面使用"specs":[{}]描述包含的对象）、array（数组类型，支持int、double、float、text、struct）",
                        "specs": {
                            "min": "参数最小值（int、float、double类型特有）",
                            "max": "参数最大值（int、float、double类型特有）",
                            "unit": "属性单位（int、float、double类型特有，非必填）",
                            "unitName": "单位名称（int、float、double类型特有，非必填）",
                            "size": "数组元素的个数，最大512（array类型特有）。",
                            "step": "步长（text、enum类型无此参数）",
                            "length": "数据长度，最大10240（text类型特有）。",
                            "0": "0的值（bool类型特有）",
                            "1": "1的值（bool类型特有）",
                            "item": {
                                "type": "数组元素的类型（array类型特有）"
                            }
                        }
                    }
                }
            ],
            "method": "事件对应的方法名称（根据identifier生成）"
        }
    ],
    "services": [
        {
            "identifier": "服务唯一标识符（产品下唯一，其中set/get是根据属性的accessMode默认生成的服务。）",
            "name": "服务名称",
            "desc": "服务描述",
            "required": "是否是标准功能的必选服务",
            "callType": "async（异步调用）或sync（同步调用）",
            "inputData": [
                {
                    "identifier": "入参唯一标识符",
                    "name": "入参名称",
                    "dataType": {
                        "type": "属性类型: int（原生）、float（原生）、double（原生）、text（原生）、date（String类型UTC毫秒）、bool（0或1的int类型）、enum（int类型，枚举项定义方法与bool类型定义0和1的值方法相同）、struct（结构体类型，可包含前面7种类型，下面使用"specs":[{}]描述包含的对象）、array（数组类型，支持int、double、float、text、struct）",
                        "specs": {
                            "min": "参数最小值（int、float、double类型特有）",
                            "max": "参数最大值（int、float、double类型特有）",
                            "unit": "属性单位（int、float、double类型特有，非必填）",
                            "unitName": "单位名称（int、float、double类型特有，非必填）",
                            "size": "数组元素的个数，最大512（array类型特有）。",
                            "step": "步长（text、enum类型无此参数）",
                            "length": "数据长度，最大10240（text类型特有）。",
                            "0": "0的值（bool类型特有）",
                            "1": "1的值（bool类型特有）",
                            "item": {
                                "type": "数组元素的类型（array类型特有）"
                                }
                            }
                        }
                    }
                }
            ],
            "outputData": [
                {
                    "identifier": "出参唯一标识符",
                    "name": "出参名称",
                    "dataType": {
                        "type": "属性类型: int（原生）、float（原生）、double（原生）、text（原生）、date（String类型UTC毫秒）、bool（0或1的int类型）、enum（int类型，枚举项定义方法与bool类型定义0和1的方法相同）、struct（结构体类型，可包含前面7种类型，下面使用"specs":[{}]描述包含的对象）、array（数组类型，支持int、double、float、text、struct）",
                        "specs": {
                            "min": "参数最小值（int、float、double类型特有）",
                            "max": "参数最大值（int、float、double类型特有）",
                            "unit": "属性单位（int、float、double类型特有，非必填）",
                            "unitName": "单位名称（int、float、double类型特有，非必填）",
                            "size": "数组元素的个数，最大512（array类型特有）。",
                            "step": "步长（text、enum类型无此参数）",
                            "length": "数据长度，最大10240（text类型特有）。",
                            "0": "0的值（bool类型特有）",
                            "1": "1的值（bool类型特有）",
                            "item": {
                                "type": "数组元素的类型（array类型特有）"
                            }
                        }
                    }
                }
            ],
            "method": "服务对应的方法名称（根据identifier生成）"
        }
    ]
}