DeviceDefinitionsResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/aqara/json-schema/aqara-device-definitions-response-schema.json",
  "title": "DeviceDefinitionsResponse",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/aiot-api-zh.yaml#/components/schemas/DeviceDefinitionsResponse",
  "allOf": [
    {
      "$ref": "#/$defs/BaseResponse"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/DeviceDefinition"
          }
        }
      }
    }
  ],
  "$defs": {
    "BaseParameter": {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "数据类型。<br />\n<table>\n  <thead>\n    <tr>\n      <th>名称</th>\n      <th>类型</th>\n      <th>说明</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Bool</td>\n      <td>布尔型</td>\n      <td>真或假（true/false）。</td>\n    </tr>\n    <tr>\n      <td>Integer</td>\n      <td>整型</td>\n      <td>整数类型。</td>\n    </tr>\n    <tr>\n      <td>Float</td>\n      <td>浮点型</td>\n      <td>带小数的数字。</td>\n    </tr>\n    <tr>\n      <td>String</td>\n      <td>字符型</td>\n      <td>字符串。</td>\n    </tr>\n    <tr>\n      <td>Struct</td>\n      <td>结构体</td>\n      <td>Aqara 自定义的结构数据，形式为 JSON 字符串。<br />可以包含多种类型字段。</td>\n    </tr>\n    <tr>\n      <td>Enum</td>\n      <td>枚举</td>\n      <td>枚举类型，定义有限个取值。</td>\n    </tr>\n    <tr>\n      <td>List[X]</td>\n      <td>列表</td>\n      <td>元素类型为 X 的列表，形式为 JSON 字符串。<br />X 可为 Integer、Float、String、Struct、Enum。</td>\n    </tr>\n    <tr>\n      <td>Data</td>\n      <td>数据块</td>\n      <td>16 进制字符串（Hex String），如 \"0x01AB3F\"。</td>\n    </tr>\n  </tbody>\n</table>\n",
          "enum": [
            "Bool",
            "Float",
            "Integer",
            "Enum",
            "String",
            "Struct",
            "List[X]",
            "Data"
          ]
        },
        "min": {
          "type": [
            "number",
            "null"
          ],
          "description": "最小值。",
          "format": "double"
        },
        "max": {
          "type": [
            "number",
            "null"
          ],
          "description": "最大值。",
          "format": "double"
        },
        "supportedValues": {
          "description": "枚举值列表。仅当 parameter.type 为 Enum 时，此字段有意义。",
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/KeyValue"
          }
        },
        "unit": {
          "description": "单位。仅当 parameter.type 为 Integer 或 Float 时，此字段有意义。",
          "type": [
            "string",
            "null"
          ]
        },
        "step": {
          "description": "步长。仅当 parameter.type 为 Integer 或 Float 时，此字段有意义。",
          "type": [
            "number",
            "null"
          ],
          "format": "double"
        }
      }
    },
    "BaseResponse": {
      "type": "object",
      "required": [
        "type",
        "version",
        "msgId",
        "code"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "消息类型。"
        },
        "version": {
          "type": "string",
          "description": "接口版本。"
        },
        "msgId": {
          "type": "string",
          "description": "消息 ID。"
        },
        "code": {
          "type": "integer",
          "description": "业务状态码，0 表示成功。"
        },
        "message": {
          "type": "string",
          "description": "提示信息。"
        }
      }
    },
    "Command": {
      "type": "object",
      "required": [
        "commandCode"
      ],
      "properties": {
        "commandCode": {
          "type": "string",
          "description": "命令编码（如 MoveToXYColor）。"
        },
        "fields": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CommandField"
          },
          "description": "命令参数字段列表。"
        }
      }
    },
    "CommandField": {
      "type": "object",
      "required": [
        "fieldCode",
        "parameter"
      ],
      "properties": {
        "fieldCode": {
          "type": "string",
          "description": "参数字段编码（如 ColorX, ColorY, Time）。"
        },
        "parameter": {
          "$ref": "#/$defs/CommandFieldParameter"
        }
      }
    },
    "CommandFieldParameter": {
      "allOf": [
        {
          "$ref": "#/$defs/BaseParameter"
        },
        {
          "type": "object",
          "required": [
            "mandatory"
          ],
          "properties": {
            "mandatory": {
              "type": "boolean",
              "description": "是否必填。"
            }
          }
        }
      ]
    },
    "DeviceDefinition": {
      "type": "object",
      "required": [
        "deviceId",
        "name",
        "deviceTypesList",
        "endpoints"
      ],
      "properties": {
        "deviceId": {
          "type": "string",
          "description": "设备 ID。"
        },
        "gatewayId": {
          "type": [
            "string",
            "null"
          ],
          "description": "此设备所绑定的网关 ID。\n如果 `gatewayId` 等于 `deviceId`，表示这个设备自身是网关。\n如果 `gatewayId` 为 `null` 或空字符串，表示这个设备是不带子设备的直连网关或第三方接入设备。\n"
        },
        "name": {
          "type": "string",
          "description": "设备名称。"
        },
        "deviceTypesList": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "设备类型列表。"
        },
        "endpoints": {
          "type": "array",
          "description": "端点列表。",
          "items": {
            "$ref": "#/$defs/Endpoint"
          }
        }
      }
    },
    "DeviceFunction": {
      "type": "object",
      "required": [
        "functionCode"
      ],
      "properties": {
        "functionCode": {
          "type": "string",
          "description": "功能编码（如 LevelControl, ColorControl, Output）。"
        },
        "traits": {
          "type": "array",
          "description": "功能点列表。",
          "items": {
            "$ref": "#/$defs/Trait"
          }
        },
        "commands": {
          "type": "array",
          "description": "命令列表",
          "items": {
            "$ref": "#/$defs/Command"
          }
        }
      }
    },
    "Endpoint": {
      "type": "object",
      "required": [
        "endpointId",
        "endpointName",
        "deviceType",
        "functions"
      ],
      "properties": {
        "endpointId": {
          "type": "integer",
          "description": "端点 ID。"
        },
        "endpointName": {
          "type": "string",
          "description": "端点名称。"
        },
        "deviceType": {
          "type": "string",
          "description": "设备类型。"
        },
        "functions": {
          "type": "array",
          "description": "功能列表。",
          "items": {
            "$ref": "#/$defs/DeviceFunction"
          }
        }
      }
    },
    "FlexibleValue": {
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "type": "integer"
        },
        {
          "type": "number",
          "format": "double"
        },
        {
          "type": "string"
        }
      ],
      "description": "动态值，具体类型取决于 trait/command 定义。\n推荐值类型来源规则：\n1) trait 场景优先读取同级 parameter.type；\n2) command 场景优先读取对应 field 的 parameter.type；\n3) 当 parameter.type=Enum 时，值类型是string；\n4) 若缺少 parameter 或类型未识别，按 string 兜底并保留原始值。\n"
    },
    "KeyValue": {
      "type": "object",
      "description": "键值对。",
      "required": [
        "key",
        "value"
      ],
      "properties": {
        "key": {
          "type": "string",
          "description": "键。"
        },
        "value": {
          "type": "string",
          "description": "值。"
        }
      }
    },
    "Trait": {
      "type": "object",
      "required": [
        "traitCode",
        "parameter"
      ],
      "properties": {
        "traitCode": {
          "type": "string",
          "description": "功能点代码（如 CurrentLevel, ColorTemperature, OnOff）。"
        },
        "parameter": {
          "$ref": "#/$defs/TraitParameter",
          "description": "功能点属性。"
        },
        "value": {
          "$ref": "#/$defs/FlexibleValue",
          "description": "当前值。类型与 parameter.type 的值保持一致。"
        },
        "time": {
          "type": "integer",
          "format": "int64",
          "description": "值更新时间（毫秒级 UTC 时间戳）。"
        }
      }
    },
    "TraitParameter": {
      "allOf": [
        {
          "$ref": "#/$defs/BaseParameter"
        },
        {
          "type": "object",
          "required": [
            "readable",
            "writable",
            "subscribable"
          ],
          "properties": {
            "readable": {
              "type": "boolean",
              "description": "是否可读。",
              "default": true
            },
            "writable": {
              "type": "boolean",
              "description": "是否可写。",
              "default": true
            },
            "subscribable": {
              "type": "boolean",
              "description": "是否可订阅。",
              "default": true
            }
          }
        }
      ]
    }
  }
}