在能力架构文档中构建和使用类型定义 - 的托管集成 AWS IoT Device Management
原始类型定义命名空间类型定义

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

在能力架构文档中构建和使用类型定义

架构中的所有元素都解析为类型定义。这些类型定义要么是原始类型定义（例如布尔值、字符串、数字），要么是命名空间类型定义（为方便起见，根据原始类型定义构建的类型定义）。

定义自定义架构时，可以使用原始定义和命名空间类型定义。

原始类型定义

原始类型定义是托管集成中定义的所有类型定义的基石。所有命名空间定义，包括自定义类型定义，都通过$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过滤器设置为 ListSchemaVersionsAPI。definition

matter 类型

使用 ListSchemaVersionsAPI 在matter命名空间下查找数据类型matter，Type筛选器设置为definition。Namespace

aws 类型

使用 ListSchemaVersionsAPI 在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"