本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 在能力架构文档中构建和使用类型定义架构中的所有元素都解析为类型定义。这些类型定义要么是*原始类型定义*（例如布尔值、字符串、数字），要么是*命名空间类型定义*（为方便起见，根据原始类型定义构建的类型定义）。定义自定义架构时，可以使用原始定义和命名空间类型定义。 **Contents** + [原始类型定义](#primitive-type-definitions) + [布尔运算](#boolean-types) + [整数类型支持](#integers-support) + [数字](#numbers) + [字符串](#strings) + [null](#nulls) + [数组](#arrays) + [对象](#objects) + [命名空间类型定义](#namespaced-type-definitions) + [`案件`类型](#matter-types) + [a@@ `ws` 类型](#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`正在验证该值，则以下条件必须为真： + `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`正在验证该值，则以下条件必须为真： + `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 } ``` ### 字符串字符串类型支持以下内容： + `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`正则表达式的值 + `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`— 此关键字控制如何处理额外属性。额外属性是指名称未在 properties 关键字中列出或与中的任何正则表达式匹配的属性`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`名空间。要查找可用的命名空间类型定义，请使用`Type`过滤器设置为 [ListSchemaVersions](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListSchemaVersions.html)API。`definition` ### `案件`类型使用 [ListSchemaVersions](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListSchemaVersions.html)API 在`matter`命名空间下查找数据类型`matter`，`Type`筛选器设置为`definition`。`Namespace` ### a@@ `ws` 类型使用 [ListSchemaVersions](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListSchemaVersions.html)API 在`aws`命名空间下查找数据类型`aws`，`Type`筛选器设置为`definition`。`Namespace` #### 位图类型定义位图有两个必需的属性： + `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" ```