本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在功能結構描述文件中建置和使用類型定義結構描述中的所有元素都會解析為類型定義。這些類型定義可以是*基本類型定義* （例如布林值、字串、數字）或*命名空間類型定義* （為了方便起見，從基本類型定義建置的類型定義）。當您定義自訂結構描述時，您可以使用基本定義和命名空間類型定義。 **Contents** + [基本類型定義](#primitive-type-definitions) + [布林值](#boolean-types) + [整數類型支援](#integers-support) + [數字](#numbers) + [Strings](#strings) + [Null](#nulls) + [陣列](#arrays) + [物件](#objects) + [命名空間類型定義](#namespaced-type-definitions) + [`matter` 類型](#matter-types) + [`aws` 類型](#aws-types) + [點陣圖類型定義](#bitmap-type-definition) + [列舉類型定義](#enum-type-definition) ## 基本類型定義基本類型定義是受管整合中定義之所有類型定義的建置區塊。所有命名空間定義，包括自訂類型定義，都可以透過 `$ref`關鍵字或 `type`關鍵字解析為基本類型定義。所有基本類型皆可使用 `nullable`關鍵字，而且您可以使用 `type`關鍵字識別所有基本類型。 ### 布林值布林值類型支援預設值。範例定義： ``` { "type" : "boolean", "default" : "false", "nullable" : true } ``` ### 整數類型支援整數類型支援下列項目： + `default` 值 + `maximum` 值 + `minimum` 值 + `exclusiveMaximum` 值 + `exclusiveMinimum` 值 + `multipleOf` 值如果 `x`是正在驗證的值，則下列項目必須是 true： + `x` ≥ `minimum` + `x` > `exclusiveMinimum` + `x` < `exclusiveMaximum` **注意** 零小數部分的數字會被視為整數，但浮點數會遭到拒絕。 ``` 1.0 // Schema-Compliant 3.1415926 // NOT Schema-Compliant ``` 雖然您可以同時指定 `minimum`和 `exclusiveMinimum`或 `maximum`和 `exclusiveMaximum`，但不建議同時使用兩者。範例定義： ``` { "type" : "integer", "default" : 2, "nullable" : true, "maximum" : 10, "minimum" : 0, "multipleOf": 2 } ``` 替代定義： ``` { "type" : "integer", "default" : 2, "nullable" : true, "exclusiveMaximum" : 11, "exclusiveMinimum" : -1, "multipleOf": 2 } ``` ### 數字將數字類型用於任何數字類型，包括整數和浮點數。數字類型支援下列項目： + `default` 值 + `maximum` 值 + `minimum` 值 + `exclusiveMaximum` 值 + `exclusiveMinimum` 值 + `multipleOf` 值。倍數可以是浮點數。如果 `x`是正在驗證的值，則下列項目必須是 true： + `x` ≥ `minimum` + `x` > `exclusiveMinimum` + `x` < `exclusiveMaximum` 雖然您可以同時指定 `minimum`和 `exclusiveMinimum`或 `maximum`和 `exclusiveMaximum`，但不建議同時使用兩者。範例定義： ``` { "type" : "number", "default" : 0.4, "nullable" : true, "maximum" : 10.2, "minimum" : 0.2, "multipleOf": 0.2 } ``` 替代定義： ``` { "type" : "number", "default" : 0.4, "nullable" : true, "exclusiveMaximum" : 10.2, "exclusiveMinimum" : 0.2, "multipleOf": 0.2 } ``` ### Strings 字串類型支援下列項目： + `default` 值 + 長度限制（必須是非負數），包括 `maxLength`和 `minLength`值 + `pattern` 規則表達式的值當您定義規則表達式時，如果表達式符合字串中的任何位置，則字串有效。例如，規則表達式會`p`比對任何包含 p 的字串，例如 "apple"，而不只是字串 "p"。為了清楚起見，建議您使用包圍規則表達式 `^...$`（例如 `^p$`)，除非您有特定理由不這樣做。範例定義： ``` { "type" : "string", "default" : "defaultString", "nullable" : true, "maxLength": 10, "minLength": 1, "pattern" : "^([0-9a-fA-F]{2})+$" } ``` ### Null Null 類型僅接受單一值：`null`。範例定義： ``` { "type": "null" } ``` ### 陣列陣列類型支援下列項目： + `default` — 將用作預設值的清單。 + `items` — 對所有陣列元素施加的 JSON 類型定義。 + 長度限制（必須是非負數） + `minItems` + `maxItems` + `pattern` Regex 的值 + `uniqueItems` — 布林值，指出陣列中的元素是否需要唯一 + `prefixItems` — 陣列，其中每個項目都是對應至文件陣列每個索引的結構描述。也就是說，第一個元素驗證輸入陣列的第一個元素的陣列，第二個元素驗證輸入陣列的第二個元素，以此類推。範例定義： ``` { "type": "array", "default": ["1", "2"], "items" : { "type": "string", "pattern": "^([a-zA-Z0-9_ -/]+)$" }, "minItems" : 1, "maxItems": 4, "uniqueItems" : true, } ``` 陣列驗證的範例： ``` //Examples: ["1", "2", "3", "4"] // Schema-Compliant [] // NOT Schema-Compliant: minItems=1 ["1", "1"] // NOT Schema-Compliant: uniqueItems=true ["{"] // NOT Schema-Compliant: Does not match the RegEx pattern. ``` 使用元組驗證的替代定義： ``` { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "string" }, { "enum": ["Street", "Avenue", "Boulevard"] }, { "enum": ["NW", "NE", "SW", "SE"] } ] } //Examples: [1600, "Pennsylvania", "Avenue", "NW"] // Schema-Compliant // And, by default, it's also okay to add additional items to end: [1600, "Pennsylvania", "Avenue", "NW", "Washington"] // Schema-Compliant ``` ### 物件物件類型支援下列項目： + 屬性限制條件 + `properties` — 使用 `properties`關鍵字定義物件的屬性（鍵/值對）。的值`properties`是物件，其中每個索引鍵都是屬性的名稱，而每個值都是用來驗證該屬性的結構描述。此`properties`關鍵字會忽略不符合關鍵字中任何屬性名稱的任何屬性。 + `required` — 預設不需要`properties`關鍵字定義的屬性。不過，您可以使用 `required`關鍵字提供必要屬性的清單。`required` 關鍵字接受零個或多個字串的陣列。每個字串都必須是唯一的。 + `propertyNames` — 此關鍵字允許控制屬性名稱的 RegEx 模式。例如，您可能想要強制執行物件的所有屬性都具有遵循特定慣例的名稱。 + `patternProperties` — 這會將規則表達式映射至結構描述。如果屬性名稱符合指定的規則運算式，則屬性值必須驗證對應的結構描述。例如，使用 `patternProperties`指定值應符合特定結構描述，並指定特定類型的屬性名稱。 + `additionalProperties` — 此關鍵字控制如何處理額外的屬性。額外屬性是名稱未列在屬性關鍵字中的屬性，或符合中任何規則表達式的屬性`patternProperties`。根據預設，允許其他屬性。將此欄位設定為 `false`表示不允許其他屬性。 + `unevaluatedProperties` — 此關鍵字類似於，`additionalProperties`但它可以識別子結構描述中宣告的屬性。 `unevaluatedProperties` 透過收集在處理結構描述時成功驗證的任何屬性，並使用這些屬性作為允許的屬性清單。這可讓您執行更複雜的動作，例如有條件地新增屬性。如需詳細資訊，請參閱下列範例。 + `anyOf` — 此關鍵字的值必須是非空白陣列。陣列的每個項目都必須是有效的 JSON 結構描述。如果執行個體成功驗證*至少一個*由此關鍵字值定義的結構描述，則執行個體會成功對此關鍵字進行驗證。 + `oneOf` — 此關鍵字的值必須是非空白陣列。陣列的每個項目都必須是有效的 JSON 結構描述。如果執行個體成功針對此關鍵字的值所定義的*確切*結構描述進行驗證，則會成功對此關鍵字進行驗證。必要範例： ``` { "type": "object", "required": ["test"] } // Schema Compliant { "test": 4 } // NOT Schema Compliant {} ``` PropertyNames 範例： ``` { "type": "object", "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } // Schema Compliant { "_a_valid_property_name_001": "value" } // NOT Schema Compliant { "001 invalid": "value" } ``` PatternProperties 範例： ``` { "type": "object", "patternProperties": { "^S_": { "type": "string" }, "^I_": { "type": "integer" } } } // Schema Compliant { "S_25": "This is a string" } { "I_0": 42 } // NOT Schema Compliant { "S_0": 42 } // Value must be a string { "I_42": "This is a string" } // Value must be an integer ``` AdditionalProperties 範例： ``` { "type": "object", "properties": { "test": { "type": "string" } }, "additionalProperties": false } // Schema Compliant { "test": "value" } OR {} // NOT Schema Compliant { "notAllowed": false } ``` UnevaluatedProperties 範例： ``` { "type": "object", "properties": { "standard_field": { "type": "string" } }, "patternProperties": { "^@": { "type": "integer" } // Allows properties starting with '@' }, "unevaluatedProperties": false // No other properties allowed } // Schema Compliant { "standard_field": "some value", "@id": 123, "@timestamp": 1678886400 } // This passes because "standard_field" is evaluated by properties, // "@id" and "@timestamp" are evaluated by patternProperties, // and no other properties remain unevaluated. // NOT Schema Compliant { "standard_field": "some value", "another_field": "unallowed" } // This fails because "another_field" is unevaluated and doesn't match // the @ pattern, leading to a violation of unevaluatedProperties: false ``` AnyOf 範例： ``` { "anyOf": [ { "type": "string", "maxLength": 5 }, { "type": "number", "minimum": 0 } ] } // Schema Compliant "short" 12 // NOT Schema Compliant "too long" -5 ``` OneOf 範例： ``` { "oneOf": [ { "type": "number", "multipleOf": 5 }, { "type": "number", "multipleOf": 3 } ] } // Schema Compliant 10 9 // NOT Schema compliant 2 // Not a multiple of either 5 or 3 15 // Multiple of both 5 and 3 is rejected. ``` ## 命名空間類型定義命名空間類型定義是從基本類型建置的類型。這些類型必須遵循 `{{namespace}}.{{typename}}.` Managed Integrations 在 `aws`和 `matter` 命名空間下提供預先定義類型的格式。您可以將任何命名空間用於自訂類型，預留`aws`和`matter`命名空間除外。若要尋找可用的命名空間類型定義，請使用 [ListSchemaVersions](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListSchemaVersions.html) API，並將`Type`篩選條件設定為 `definition`。 ### `matter` 類型使用 [ListSchemaVersions](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListSchemaVersions.html) API 在`matter`命名空間下尋找資料類型，並將`Namespace`篩選條件設定為 `matter`，並將`Type`篩選條件設定為 `definition`。 ### `aws` 類型使用 [ListSchemaVersions](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListSchemaVersions.html) API 在`aws`命名空間下尋找資料類型，並將`Namespace`篩選條件設定為 `aws`，並將`Type`篩選條件設定為 `definition`。 #### 點陣圖類型定義點陣圖有兩個必要的屬性： + `type` 必須是物件 + `properties` 必須是包含每個位元定義的物件。每個位元都是具有屬性 `extrinsicId`和的物件`value`。每個位元的值必須是整數，最小值為 0，最大值至少為 1。範例點陣圖定義： ``` { "title" : "Sample Bitmap Type", "description" : "Type definition for SampleBitmap.", "$ref" : "/schema-versions/definition/aws.bitmap@1.0 ", "type" : "object", "additionalProperties" : false, "properties" : { "Bit1" : { "extrinsicId" : "0x0000", "value" : { "type" : "integer", "maximum" : 1, "minimum" : 0 } }, "Bit2" : { "extrinsicId" : "0x0001", "value" : { "type" : "integer", "maximum" : 1, "minimum" : 0 } } } } // Schema Compliant { "Bit1": 1, "Bit1": 0 } // NOT Schema Compliant { "Bit1": -1, "Bit1": 0 } ``` #### 列舉類型定義列舉需要三個屬性： + `type` 必須是物件 + `enum` 必須是一組唯一字串，其中至少有一個項目 + `extrinsicIdMap` 是具有列舉值屬性的物件。每個屬性的值應該是對應至列舉值的外部識別符。列舉定義範例： ``` { "title" : "SampleEnum Type", "description" : "Type definition for SampleEnum.", "$ref" : "/schema-versions/definition/aws.enum@1.0", "type" : "string", "enum" : [ "EnumValue0", "EnumValue1", "EnumValue2" ], "extrinsicIdMap" : { "EnumValue0" : "0", "EnumValue1" : "1", "EnumValue2" : "2" } } // Schema Compliant "EnumValue0" "EnumValue1" "EnumValue2" // NOT Schema Compliant "NotAnEnumValue" ```