本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
在功能結構描述文件中建置和使用類型定義
結構描述中的所有元素都會解析為類型定義。這些類型定義可以是基本類型定義 （例如布林值、字串、數字） 或命名空間類型定義 （為了方便起見，從基本類型定義建立的類型定義）。
當您定義自訂結構描述時，您可以使用基本定義和命名空間類型定義。
基本類型定義
基本類型定義是受管整合中定義之所有類型定義的建置區塊。所有命名空間定義，包括自訂類型定義，都可以透過 $ref關鍵字或 type關鍵字解析為基本類型定義。
所有基本類型都可以使用 nullable關鍵字為 null，而且您可以使用 type關鍵字來識別所有基本類型。
布林值
布林值類型支援預設值。
範例定義：
{ "type" : "boolean", "default" : "false", "nullable" : true }
整數類型支援
整數類型支援下列項目：
-
default值 -
maximum值 -
minimum值 -
exclusiveMaximum值 -
exclusiveMinimum值 -
multipleOf值
如果 x是正在驗證的值，則下列項目必須是 true：
-
x≥minimum x>exclusiveMinimumx<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>exclusiveMinimumx<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
-
-
patternRegex 的值 -
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.aws和 matter 命名空間下提供預先定義類型的格式。您可以將任何命名空間用於自訂類型，預留aws和matter命名空間除外。
若要尋找可用的命名空間類型定義，請使用 ListSchemaVersions API，並將Type篩選條件設定為 definition。
matter 類型
使用 ListSchemaVersions API 在matter命名空間下尋找資料類型，並將Namespace篩選條件設定為 matter，並將Type篩選條件設定為 definition。
aws 類型
使用 ListSchemaVersions 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"
