類型定義的結構描述

下列各節詳細說明用於類型定義的結構描述。

$id

$id 元素可識別結構描述定義。它必須遵循此結構：

• 從 /schema-versions/ URI 字首開始

• 包含definition結構描述類型

• 使用正斜線 (/) 做為 URI 路徑分隔符號

• 包含結構描述身分，片段以句點 (.) 分隔

• 使用 @ 字元來分隔結構描述 ID 和版本

• 以 semver 版本結尾，使用句點 (.) 分隔版本片段

結構描述身分的開頭必須是長度為 3-12 個字元的根命名空間，後面接著選用的子命名空間和名稱。

轉換器版本包含 MAJOR 版本 （最多 3 位數）、MINOR 版本 （最多 3 位數） 和選用的 PATCH 版本 （最多 4 位數）。

注意

您無法使用預留命名空間aws或 matter

範例 $id

/schema-version/capability/aws.Recording@1.0

$ref

$ref 元素參考系統中現有的類型定義。它遵循與 $id元素相同的限制條件。

注意

類型定義或功能必須使用 $ref 檔案中提供的值存在。

範例 $ref

/schema-version/definition/aws.capability@1.0

name

名稱元素是字串，代表結構描述文件中的實體名稱。它通常包含縮寫，並且必須遵循這些規則：

• 僅包含英數字元、句點 (.)、斜線 (/)、連字號 (-) 和空格

• 從字母開始

• 最多 192 個字元

名稱元素用於 Amazon Web Services 主控台 UI 和 文件。

範例名稱

Door Lock
On/Off
Wi-Fi Network Management
PM2.5 Concentration Measurement
RTCSessionController
Energy EVSE

標題

標題元素是結構描述文件所代表實體的描述性字串。它可以包含任何字元，並用於文件中。

範例標題

Real-time Communication (RTC) Session Controller
Energy EVSE Capability

description

description 元素提供結構描述文件所代表實體的詳細說明。它可以包含任何字元，並用於文件中。

範例描述

Electric Vehicle Supply Equipment (EVSE) is equipment used to charge an Electric Vehicle (EV) or Plug-In Hybrid Electric Vehicle. 
            This capability provides an interface to the functionality of Electric Vehicle Supply Equipment (EVSE) management.

extrinsicId

extrinsicId 元素代表在 Amazon Web Services IoT 系統外部管理的識別符。對於事項功能，它fieldId會根據內容對應至 clusterId、eventId、、 attributeId commandId或 。

extrinsicId 可以是字串化十進位整數 (1-10 位數） 或字串化十六進位整數 (0x 或 0X 字首，後面接著 1-8 個十六進位位數）。

注意

對於 AWS，廠商 ID (VID) 為 0x1577，對於事項，則為 0。系統會確保自訂結構描述不會將這些預留 VIDs用於 功能。

範例 extrinsicIds

0018
0x001A
0x15771002

extrinsicProperties

extrinsicProperties 元素包含一組在外部系統中定義的屬性，但在資料模型中維護。對於事項功能，它會映射到 ZCL 叢集內不同的未建模或部分建模元素、屬性、命令或事件。

外部屬性必須遵循下列限制：

• 屬性名稱必須為英數字元，不含空格或特殊字元

• 屬性值可以是任何 JSON 結構描述值

• 最多 20 個屬性

系統支援各種 extrinsicProperties，包括 access、apiMaturity、cliFunctionName、 cli等。這些屬性有助於 ACL 轉換 AWS （反之亦然） 資料模型。

注意

功能的 action、property、 event和 struct 欄位元素支援外部屬性，但功能或叢集本身不支援。